API v2 reference

This document contains detailed information about the Skytap Cloud 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.

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. Do not include v2 in the Content-Type header.

Notes

  • You do not need to specify v1 in your v1 API requests. If a version number is not specified, Skytap Cloud processes the request as a v1 request.
  • For more information about crafting a Skytap Cloud 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 have not 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

If the response to a GET request to a resource collection does not 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 are 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.

    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 are not documented. These are unsupported elements, and there is no guarantee that they will exist in future revisions of the API. Do not build dependencies on these unsupported and undocumented elements.

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 Cloud 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 backwards-compatibility.

The following fields are defined:

Field Name Type Access Description
id string ro Environment identifier
url URI ro URI reference for the environment
name string rw User-defined name of the environment. Limited to 255 characters. UTF-8 character type. Will default to source template’s name if null is provided.
errors array ro Describes any errors with the environment
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.
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:
  • stopped: all VMs are stopped
  • suspended: one or more VMs are suspended, others are stopped
  • running: one or more VMs are running

For information about editing this field, see Run/Stop/Suspend/Restart Environment

UTF-8 character type.

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.
description string rw User-defined description of the environment. Limited to 1000 characters. Null allowed. UTF-8 character type.
last_run timestamp ro The date and time that the environment was last run. If null, the environment has not been run.
If null, the environment has not been run.
owner_url URI ro URI reference of the environment’s owner (e.g., https://cloud.skytap.com/v2/users/123456)
owner_name string ro Name of the environment’s owner
owner_id integer ro User ID of the environment’s owner
owner integer wo User ID of the environment’s owner. This field is only used to change the environment owner; it is not displayed during a GET request.
vm_count integer ro Number of VMs in the environment
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
container_hosts_count integer ro Number of container host VMs in the template
storage integer ro Amount of storage space consumed by the environment (in MiB). This is calculated by adding the total storage space consumed by all disks in all of the environment’s VMs.
network_count integer ro Number of networks in the environment
created_at timestamp ro The date and time that the environment was created
svms integer ro The number of SVMs this environment will consume when running. For information about how SVMs are calculated, see Usage Overview.
can_save_as_template 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_copy 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_delete 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_change_state 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_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_edit 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).
tags array ro Array of tags attached to the environment. To add or remove environment tags, see Environment tags sub-resource.
alerts array ro Environment-wide warnings or informational alerts.
outbound_traffic Boolean rw Indicates whether networks in the environment can send outbound traffic.
routable Boolean rw Indicates whether networks within the environment can route traffic to one another.
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.
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 quota.

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

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)
published_service_count integer ro Number of published services across all VMs in the environment
vpn_count integer ro Number of VPNs attached to networks in the environment
public_ip_count integer ro Number of public IPs attached to network adapters across all VMs in the environment
schedule_count integer ro Number of schedules that include this environment in an action
publish_set_count integer ro Number of publish sets configured for this environment. Note: This number only counts published sets; it does not count published URLs within those sets.
project_count integer ro Number of projects that this environment belongs to
note_count integer ro Number of environment notes in this environment
sequencing_enabled Boolean ro If true, VM sequencing is on.
svms_by_architecture object ro Lists the number of x86 and power SVMs consumed by VMs in the environment. Example contents:"svms_by_architecture": { "x86": 0, "power": 2}
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.
suspend_on_idle integer rw The number of seconds an environment can be idle before it is automatically suspended.
If suspend_on_idle and suspend_at_time are both null, automatic suspend is disabled.
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.
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 shut down is off.
shutdown_on_idle integer rw The number of seconds an environment can be idle before it is automatically shut down.
If shutdown_on_idle and shutdown_at_time are both null, automatic shut down is disabled.
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.

Environments v2 sub-resources

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

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

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 are not 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 is not available if the scope parameter is me.

created_at

string

Filters by environment creation date. Options:

  • In the past x hours: now-xh+to+now
  • In the past x days: now-xd+to+now
  • In the past x months: now-xm+to+now
  • Not in the past x days: to+now-xd
  • Custom: timestamp+to+timestamp

last_run

string

Filters by environment last run date. Options:

  • In the past x hours: now-xh+to+now
  • In the past x days: now-xd+to+now
  • In the past x months: now-xm+to+now
  • Not in the past x days: 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 SVM count: 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 will not 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:

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

    GET https://cloud.skytap.com/v2/configurations?scope=company

  2. 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).
  3. 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 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 does not 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.

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 do not 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 will not 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 will power off the VMs and then return 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 are not legal ‘target’ states.

Response

The response will return immediately, even if the transition is not 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 cannot be suspended. If the environment runstate is changed to suspended, VMs that cannot 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"
    ]
}
  • 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 is not 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 cannot 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 Cloud 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 cannot 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 Cloud 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 cannot 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 Cloud 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 cannot 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 Cloud 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 is 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:

  1. Parse the response body from the POST request to locate the report ID.
  2. Poll the report until the ready field equals true.

    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"
    }
    
  3. 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/v2/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 do not 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
id string ro VM identifier.
name string rw User-defined name. Limited to 100 characters.

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

runstate string rw Runstate of VM. UTF-8 character type. See allowed values in parameters section of Change VM runstate below.
hardware hardware rw Hardware description. For more information, see Notes on the “hardware” element.
display_server string rw 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 below, 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 rw Used to specify a custom port number for RDP or SSH connections in the SRA browser client.
This field can be edited when the VM is powered off.

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

audio_in Boolean rw 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 rw 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.

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.
asset_id URI wo 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.

hardware_version integer ro VM hardware version number. Always null for Power VMs.
interfaces interface[] ro Array of virtual network interfaces.
To edit this array, see VM network adapters.
notes array ro Array of notes stored on the VM. Includes text and id values.
To edit this array, see VM notes.
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.
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.
containers object ro If null, the VM is not 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:
agent_versionstringVM agent version number.
agent_statusstringStatus of the VM agent.
containers_countintegerNumber of containers on this VM.
publish_set_refs publish_set_ref[] ro 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 does not 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 will not be returned.

configuration_url or 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 user data.
region_backend string ro Region that the resource is housed in (for example, US-West)
created_at timestamp ro Date and time the VM was created.

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
cpus integer rw Number of CPUs allocated to this virtual machine.
Valid range is 1 to 12. Maximum limit depends on the max_cpus setting.

This value may be changed only when the VM is powered off.

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 VMs.
cpus_per_socket integer rw for x86 VMs
ro for Power VMs

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. Always 1 for Power VMs
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 cannot 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).
ram integer rw Amount of RAM allocated to this VM.
Valid range is 256 and 131,072 (MB). Maximum limit depends on max_ram setting

This value may be changed only when the VM is powered off.

svms integer ro Number of SVMs used by this VM
guestOS string rw This field tells the underlying host which operating system the VM is running and whether nested hypervisors are enabled.
max_cpus integer ro Maximum settable CPUs for this VM
min_ram integer ro Minimum settable RAM for this VM
max_ram integer ro Maximum settable RAM for this VM
vnc_keymap string rw for x86 VMs
ro for Power VMs
Keyboard language mapping. UTF-8 character type. 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
Always null for Power VMs.
uuid integer rw for x86 VMs
ro for Power VMs
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 VMs.
disks array rw Array of virtual disks within the VM. The disk size is in MiB; it will be converted to GiB in the Skytap UI. The maximum disk size is 2096128 MiB (1.999 TiB).
storage integer ro Total amount of storage consumed by the VM in MiB. Calculated by adding the storage size of all disks within the VM.
upgradable Boolean ro If true, the VM is not on the latest supported hardware version; the VM hardware version can be upgraded through the Skytap UI
Always false for Power VMs.
time_sync_enabled Boolean rw for x86 VMs
ro for Power VMs
If true, time-sync is enabled. For more information, see Editing VM hardware and guest OS settings.
Always false for Power VMs.
rtc_start_time Unix timestamp rw for x86 VMs
ro for Power VMs
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 cannot set the rtc_start_time if time-sync is enabled
Always null for Power VMs.
instance_type string ro This field is not currently in use. It always returns as null.
copy_paste_enabled Boolean rw for x86 VMs
ro for Power VMs
If true, copy and paste is enabled between a local machine and the VM (when the VM desktop is accessed via the browser).
Always false for Power VMs.
nested_virtualization Boolean rw for x86 VMs
ro for Power VMs
If true, nested virtualization is enabled on the VM. For more information, see Enabling nested virtualization.
Always false for Power VMs.
architecture string ro Either power or x86.
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.
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.

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:

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.

{
    "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

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) cannot 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.

{
    "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 MiB; it will be converted to GiB in the Skytap UI. The minimum disk size is 2048 MiB; the maximum is 2096128 MiB (1.999 TiB).
  • This request does not 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.

{
    "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 a disk’s size

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 MiB; it is converted to GiB in the Skytap UI.
  • The minimum disk size is 2048 MiB (2 GiB), and the maximum disk size is 2096128 MiB (1.999 TiB).
  • You cannot make a disk smaller; you can make it larger.
  • This request does not 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.

{
    "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 does not 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.

{
    "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 do not 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 does not support it, you will receive an error message. Otherwise, you will be able run a VM from within the VM.

Change VM runstate

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 VMs:

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 do not 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 will not 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.

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 are not legal ‘target’ states.

Response

The response will return immediately, even if the transition is not 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 cannot 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"
}

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 SmartRDP or RDP File

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

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 :3389 will be returned
  • If the VM is not connected to a VPN, but it is configured for an RDP published service, an RDP file that connects over the published service port opening will be returned.
  • If the VM does not have an RDP published service, a SmartRDP file 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/v2/vms/<vm-id>/export_network_connections.json

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

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/v2/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:

  1. Parse the response body from the POST request to locate the report ID.
  2. Poll the report until the ready field equals true.

    GET https://cloud.skytap.com/v2/vms/111111/export_network_connections/123456.json
    
    {
       "id": "123456",
       "ready": true,
       "url": "https://cloud.skytap.com/v2/vms/111111/export_network_connections/123456",
       "notify_by_email": true,
       "email": "user@internet.net"
    }
    
  3. 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/v2/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 cannot 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.

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"
}

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"
}

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.
type string ro Read-only representation of the tag_type field.
text string rw Contents of the label. Max 255 characters.

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"
}

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 cannot 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
id integer ro Note identifier
user_id integer ro ID of the user who created the note
user object ro Representation of the user who created the note
time timestamp ro Date and time the note was created
created_at timestamp ro Date and time the note was created
updated_at timestamp ro Date and time the note was last edited
text string rw Contents of 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.

{
    "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
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 will not 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).
hostname string rw Limited to 32 characters. Valid characters are lowercase letters, numbers, and hyphens. Cannot begin or end with hyphens. Cannot be gw.
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 will not 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.
services_count integer ro Number of published services attached to the VM.
services service[] ro An array of a published services attached to the VM. To add a published service, see Published Service v2 Resource.
public_ips_count integer ro 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 public_ip_attachments[] ro 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.
NameTypeDescription
idintegerUnique ID associated with the PIP attachment to this network adapter
public_ip_attachment_keyintegerUnique ID associated with the PIP attachment to this network adapter
addressstringFor dynamic public IPs:
  • If the public IP address is deployed, the IPv4 address attached to the VM.
  • null if the VM is not running.
For static public IPs:
  • The IPv4 public IP address attached to the VM.
connect_typeintegerEither static or dynamic.
hostnamestringFor dynamic PIPs, the VM hostname used in the FQDN.
For static PIPs, null.
dns_namestringFor dynamic PIPs, the entire fully-qualified domain name for the VM. For static PIPs, null.
public_ip_keystringUnique 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 do not appear in this list.
nat_addresses object ro This object will only appear 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.
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
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
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
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.

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.

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"
}

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 cannot 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 cannot be enabled for Power VMs.

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

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"
}

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.

[
    {
        "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 cannot begin or end with a hyphen.
  • Max. of 32 characters.
Response

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

[
    {
        "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"
}

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>

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
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)
external_ip IP address ro Exposed routable IP. Connections to this IP and port (below) are routed to the internal port in the guest VM. The external IP and port are selected by Skytap.
external_port integer ro Exposed routable port. The port number is selected by Skytap.

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
}

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 cannot 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/<X>

Where “X” is equal to the port number (for example, 8080).

You cannot perform this action on VMs in templates.

Response

Status

Secondary IPs 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 IPs v2 reference URI

Secondary IPs is a resource located within the network adapter resource on environment VMs. This resource does not exist for template VMs.

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

Secondary IPs v2 resource model

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

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

Operations on v2 secondary IPs

List secondary IPs

Request

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

Response

Representation of the secondary IPs

Add a secondary IP

Request

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

{
    "address": "10.0.2.2"
}

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

Response

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

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

Edit a secondary IP

Secondary IPs cannot be edited. Instead, detach the unwanted secondary IP and create a new one.

Detach a secondary IP

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 secondary IP’s ID.

Response

Removed secondary IP.

VM user data v2 resource

(The environment VM resource and template VM resource contain 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.

VM user data v2 reference URI

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

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

VM user data 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. UTF-8 character type.

Supported operations on VM user data

Get VM user data

Request

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

Response

Contents of user data field.

Update VM user data

Request

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

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

contents: Any text you want saved in the user_data field.

This action isn’t supported for VMs in templates.

Response

Updated user data field.

Remove contents of VM user data 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 user data field.

Environment containers v2 resource

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

See also Containers v2 resource and Container registries v2 resource.

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 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)stringFilters by container host VM. Syntax:`query=vm_id:12345`(`query=vm_id%3A12345` in a URL string)
statusstringFilters by container status. Syntax:`query=status:running`(`query=status:running` in a URL string)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

[
    {
        "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. Note: Containers that are not accessible are skipped. Check the response body for the status of each container and any possible errors.
Note: Containers that are not accessible are skipped. Check the response body for the status of each container and any possible errors.
400 Containers are not 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 is not responding, container does not exist (it was 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.
[
    {
        "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
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 environment labels

Get environment labels

Request

GET https://cloud.skytap.com/v2/configurations/<configuration-id>/labels.json

  • 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 are not 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

[
    {
        "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 label(s) 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

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 1000 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 cannot 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.

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

Add label(s) to multiple environments

Request

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

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

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.
{
    "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 cannot 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 will not be deleted; it will still be available for reporting.

Response

Updated representation of the labels sub-resource.

Environment networks v2 resource

Networks are not 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
id integer ro Identifier
url URI ro URI for the resource
name string rw User defined name of the network. Limited to 255 characters. UTF-8 character type.
domain string rw Domain name for the Skytap network. Limited to 64 characters.
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).

domain can only be defined and edited for automatic networks (see network_type below).

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 29. 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.

gateway string rw Gateway IP address.
network_type string rw Type of network (must be automatic or manual)Once it is defined, this field cannot be edited.
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
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.
secondary_nameserver string rw User-provided secondary name server for this network. The secondary_nameserver is used if the primary_nameserver does not resolve.
region string ro Region that the resource is housed in (for example, US-West)
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 is not NAT-enabled.
Cannot overlap with subnet (see above).
Can be unset with "".
nat_pool_size integer ro The total number of IP addresses for external mapping. Does not appear if network is not NAT-enabled
nat_pool_remaining integer ro Remaining assignable IP addresses for NAT. Does not appear if network is not NAT-enabled
vpn_attachments array ro Representations of the relationships between this network and any VPN or Private Network Connections it is 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

{
    "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 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

{
    "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 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

{
    "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

{
    "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
id integer ro Note identifier
user_id integer ro ID of the user who created the note
user object ro Representation of the user who created the note
time timestamp ro Date and time the note was created
created_at timestamp ro Date and time the note was created
updated_at timestamp ro Date and time the note was last edited
text string rw Contents of 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"
}

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"
}

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.

Environment sharing portals v2 resource

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

Environment sharing portals v2 reference URI

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 backwards-compatibility.

Environment sharing portals v2 resource model

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

Field Name Type Access Description
id integer ro Unique ID for the sharing portal
name string rw Descriptive name of sharing portal; does not need to be unique
url string ro URL of the sharing portal resource for UI and API access
publish_set_type string rw Type of sharing portal. Either (single_url or multiple_url):
  • single_url: Single sharing portal
  • multiple_url: Sharing portal set
configuration_name string ro Name of the environment that the sharing portal provides access to
runtime_limit integer rw (Optional) The number of minutes the VM(s) can be accessed via a sharing portal. Once this limit is met, the VMs will be set to “do_not_publish”; they will not be suspended by this action. You can increase the limit to provide additional access. Null if not in use.
runtime_left_in_seconds integer ro For single_url sharing portals with a runtime_limit set, this field will display the remaining time that the sharing portal is available. For all other conditions, this field will be null.
expiration_date
expiration_date_tz
strings rw (Optional) Used to set an expiration date and time for access to the sharing portal. These fields are null if not in use.
  • expiration_date: The date and time the sharing portal expires. After this time, the VM(s) cannot be accessed via the sharing portal. Use the format: yyyy/mm/dd hh:mm:ss ("2015/11/28 10:45:00")
  • expiration_date_tz: 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.

start_time
end_time
time_zone
strings rw (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.
  • You can optionally define the time_zone for the access window. If this is not defined, your personal time zone is used. For a list of time zones, see Time Zones and UTC Offsets.
multiple_url Boolean ro Indicates whether the publish_set_type is multiple_url.
password string wo If a password is included in this field, it is required for accessing the sharing portal. If you do not want to require a password for access, enter an empty string in this field.

You cannot 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 will be empty.
  • If a password has been set, the API will return a string of 10 asterisks: **********

If ********** is sent as the value of the password element, it is ignored; the current password will not be changed.

sso_required Boolean rw This field is only visible for accounts with SSO enabled.
If true, SSO will be used to authenticate users accessing the sharing portal. If true, password (above) must be empty.
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).
vms array ro/rw Representation of VMs in the sharing portal. Description
Field NameTypeAccess
vm_refURIrwVM URI
namestringroVM name
accessstringrwVM access level. Must be one of:
  • do_not_publish (Labeled "Excluded" in the UI)
  • view_only
  • use
  • run_and_use (Labeled "Full Control" in the UI)
run_and_useBooleanroTrue if the access level is run_and_use
errorBooleanroIndicates whether the VM has an error
desktop_urlstringroAccess URL for the VM
anonymous_smart_rdp Boolean rw If true, the sharing portal will include the option to download a SmartRDP file. This file will provide access to the environment while the sharing portal is active.
False by default.
support_url string wo (Optional) Used to customize the support link that appears in the sharing portal. If this field is empty, the default help page will be used (http://help.skytap.com/#SmartClient_Help_Page.html).
String format must be one of the following:
  • http://example.com
  • https://example.com
  • mailto:support@example.com
custom_content_enabled Boolean rw If true, the sharing portal will include a tab with the contents of the custom_content field. The tab must have a name, defined in the custom_title field below.
custom_title string rw Name of the custom content tab. Max. 32 characters.

This field is required if custom_content_enabled is true.

custom_content string rw 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).

This field is required if custom_content_enabled is true.

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

Operations on v2 environment sharing portals

List sharing portals

Request

GET https://cloud.skytap.com/v2/configurations/<configuration-id>/publish_sets.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.

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</strong>&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.

Create sharing portal

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",
    "anonymous_smart_rdp": false,
    "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 Parameters

name: Sharing portal name.

Optional Parameters

When creating a sharing portal, you can include one or more of the following sets of information:

  • start_time, end_time, and time_zone
  • runtime_limit
  • expiration_date and expiration_date_tz
  • password
  • anonymous_smart_rdp
  • sso_required
  • custom_content_enabled, custom_content, custom_title, and custom_content_is_default
  • vms (with vm_ref and access)
  • support_url
Response

Representation of the new sharing portal.

{
    "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,
    "anonymous_smart_rdp": false,
    "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
}
{
    "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,
    "anonymous_smart_rdp": false,
    "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"
}

Get sharing portal

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 is 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 will not take effect if this request is made within the auto-suspend window you have 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.

Edit sharing portal

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.

Delete 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. 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 are not 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.

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

Add tag(s) to the environment

Request

PUT https://cloud.skytap.com/v2/configurations/<configuration-id>/tags.json

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

Required: One or more values, entered as an array of objects.

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.

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

Add tag(s) to multiple environments

Request

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

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

Required: One or more values, entered as an array of objects.

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.
{
    "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 will not 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.

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

Environment user data 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 user data v2 reference URI

https://cloud.skytap.com/v2/configurations/<configuration-id>/user_data.json

Environment user data 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 user data

Get environment user data

Request

GET https://cloud.skytap.com/v2/configurations/<configuration-id>/user_data.json

Response

Representation of the user_data field.

Update environment user data

Request

PUT https://cloud.skytap.com/v2/configurations/<configuration-id>/user_data.json

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

contents: Any text you want saved in the user_data field.

Response

Updated representation of the user_data field.

Remove environment user data

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 are not 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, and so on
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 will not 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 do not 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 will not 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 does not contain all four stages, the API will return an error response and Skytap will not 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

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 only recognized 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, and so on
current_stage_finished_at timestamp Time that the current stage finished executing
vm_ids array (string) The IDs of the VM instances whose runstates 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 is not 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 are 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 is not 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 is not directly runnable, and many of the template attributes in the API cannot be modified. For example, the “runstate” attribute will list the state of the VMs in this template, but it cannot 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
id string ro Template identifier
url URI ro URI reference for template
name string rw User-defined name. Limited to 255 characters. UTF-8 character type. Will default to source environment’s name with - Copy added if null is provided.
busy Boolean ro Describes if the template is busy.

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

owner integer wo User ID of the template’s owner. This field is only used to change the template owner; it is not displayed during a GET request, or if the template is in the Skytap public library.
public Boolean ro Indicates whether the template is from the Skytap public library
errors array ro Lists any template errors
owner_url URI ro Template owner’s full URL (e.g., https://cloud.skytap.com/v2/users/12345). This field does not 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 does not exist for Skytap-owned public templates.
owner_id integer ro Template owner’s ID number. This field does not exist for Skytap-owned public templates.
description string rw User-defined description. Limited to 1000 characters. Null allowed. UTF-8character type.
vm_count integer ro Number of VMs in the template
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
container_hosts_count integer ro Number of container host VMs in the template
storage integer ro Amount of storage space consumed by the template (in MiB). This is calculated by adding the total storage space consumed by all disks in all of the template’s VMs.
network_count integer ro Number of networks in the template
created_at timestamp ro The date and time that the template was created
svms integer ro The number of SVMs an environment created from this template will consume when running. For information about how SVMs are calculated, see Usage Overview.
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.
can_copy Boolean ro The user’s permissions relative to this template. These permissions are 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 cannot be modified.
can_delete Boolean ro The user’s permissions relative to this template. These permissions are 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 cannot be modified.
can_share Boolean ro The user’s permissions relative to this template. These permissions are 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 cannot be modified.
can_tag Boolean ro The user’s permissions relative to this template. These permissions are 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 cannot be modified.
tags array ro Array of tags attached to the template. To add or remove template tags, see Template tags sub-resource.
vms vm[] ro Array of virtual machines in the template
networks network[] ro Array of networks 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)
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.
user_data string ro A free-form text field that is useful in automation scenarios. For more information, see Accessing the VM Metadata Service.

user_data does not 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.

svms_by_architecture object ro Lists the number of x86 and power SVMs consumed by VMs in the template.
Example contents:"svms_by_architecture": { "x86": 0, "power": 2}

Templates v2 sub-resources

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

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

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 are not 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 is not available if the scope parameter is me or public.

created_at

string

Filters by template creation date. Options:

  • In the past x hours: now-xh+to+now
  • In the past x days: now-xd+to+now
  • In the past x months: now-xm+to+now
  • Not in the past x days: 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 x hours: now-xh+to+now
  • In the past x days: now-xd+to+now
  • In the past x months: now-xm+to+now
  • Not in the past x days: 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 SVM count: 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 will not 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 is 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:

  1. Parse the response body from the POST request to locate the report ID.
  2. Poll the report until the ready field equals true.

    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"
    }
    
  3. 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/v2/templates/exports/123456.csv

Response

Templates CSV report.

Template VMs v2 resource

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

  • VMs do not 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:

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 are not 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

  • 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 are not 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

[
    {
        "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 label(s) 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

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 1000 label values.
  • If the label category is single_value, you can only apply 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 cannot 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.

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

Add label(s) to multiple templates

Request

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

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

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.
{
    "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 cannot 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 will not be deleted; it will still be available for reporting.

Response

Updated representation of the labels sub-resource.

Template sharing portals v2 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.

Template sharing portals v2 reference URI

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 backwards-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.

Operations on v2 template sharing portals

Get sharing portal

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 is set.

List template sharing portals

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 are not 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.

[
    {
        "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: One or more values, entered as an array of objects.

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.

[
    {
        "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: One or more values, entered as an array of objects.

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.
{
    "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 will not 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.

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

Template VM sequencing stages v2 resource

Stages are not 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 will not 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 Cloud.

Account details v2 reference URI

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

Account details v2 resource model

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

Field Name Type Access Description
first_name string ro Your first name.
last_name string ro Your last name.
login_name string ro Your Skytap username.
email string rw Email associated with your user account; this is the email address that Skytap Cloud sends notifications to.
title string ro Optional title associated with the user; does not affect Skytap Cloud permissions.
time_zone string rw The time zone associated with your Skytap Cloud activities (for example, project creation time).
country_of_residence string rw The ISO 3166-1 alpha-3 code associated with your country of residence. For example, USA.
For a list of codes, see the ISO 3166-1 alpha-3 Wikipedia entry.
Note that PRK, CUB, SYR, IRN, and SDN are not accepted values.
country_of_residence_name string ro The full name of your country of residence. For example: United States of America.
wants_email Boolean ro null
This is a legacy field that was deprecated in May 2018. Marketing email preferences are now managed at http://research.skytap.com/Email-Preference-Center.html.
default_region string rw The default region for your VM imports, asset uploads, new VPNs, and new public IP addresses.
account_role string ro Your user role. This determines your level of access across the Skytap Cloud account. One of restricted_user, standard_user, user_manager, or admin.
department_name string ro The name of the department you belong to.
department_id integer ro The identifier of the department you belong to.
account_name string ro The name of your Skytap Cloud customer account.
shared drives array ro Array of shared drive objects. Each shared drive object includes the shared drive region, address, username, and password.
email_validated Boolean ro Indicates whether you have verified your email address.
primary_contact object ro Provides information about your account administrator. Includes the administrator’s first_name, last_name, login_name, and email.

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

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 are a member of.

[
  {
    "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 my API token

Request

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

With the following request headers:

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

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

Response
{
  "api_token": "1234abcd1234abcd"
}

Reset my API token

Request

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

Response
{
  "api_token": "5678aaaa5678aaaa"
}

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"
}
  • 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 cannot match the user login 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 do not match.
  • The new_password matches the login name, does not contain a non-alphabetical character, or does not 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 SVMs, SVM hours, storage, concurrent VMs, public IPs, and networks across all of the users in your account.

You must be a Skytap Cloud administrator to access the Account limits resource.

Account limits v2 reference URI

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

When you use the above URI, Skytap Cloud 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.
units string ro Specifies the unit of measure (for example, MB or integer).
limit integer (various, see description) Current resource limit for the account.
Field NameTypeAccessDescription
concurrent_svmsintegerrwThe maximum number of Skytap Virtual Machine (SVM) units that may be used at the same time; applies to SVM units consumed by x86 VMs.
concurrent_svms_powerintegerrwThe maximum number of Skytap Virtual Machine (SVM) units that may be used at the same time; applies to SVM units consumed by Power VMs.

Available only if your account is enabled for Power VMs.

concurrent_vmsintegerrwNumber of VMs that can be used at the same time.
storageintegerrwMaximum storage limit for the account, units specified in MB.
svm_hoursintegerrwMaximum number of hours of cumulative SVM usage for x86 VMs.
svm_hours_powerintegerroMaximum number of hours of cumulative SVM usage for Power VMs.Returned only if your account is enabled for Power VMs.
public_ipsintegerroMaximum number of public IP addresses.
networksintegerroMaximum number of networks.
region integer ro The name of the region that the limit applies to. If limit applies to the whole account, this parameter contains global.
usage integer ro The amount of resource in use or consumed (depending on the resource).
subscription integer ro The amount of resources you have budgeted for monthly usage; if you set the limit above the subscription, you can allow additional usage at an additional cost.
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.

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.

[
  {
    "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
  }
]
{
  "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": [
    {
      "id": "concurrent_svms",
      "units": "integer",
      "limit": 10,
      "region": "US-East",
      "usage": 0,
      "subscription": 10,
      "max_limit": 10
    },
    {
      "id": "storage",
      "units": "MB",
      "limit": 51200,
      "region": "US-East",
      "usage": 10240,
      "subscription": 51200,
      "max_limit": 51200
    },
    {
      "id": "networks",
      "units": "integer",
      "limit": 10,
      "region": "US-East",
      "usage": 2
    },
    {
      "id": "public_ips",
      "units": "integer",
      "limit": 3,
      "region": "US-East",
      "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.

[
  {
    "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 quota that is read only or where the max settable limit “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 are editing a regional limit, you must include a region parameter. If you are editing a global limit, no region is required.
Response

The updated quota.

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 cannot be created, modified, or deleted. You can only 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
id string ro Identifier.
name string ro Human-friendly name. Limited to 255 characters. UTF-8 character type.
created_at timestamp ro Date and time that the asset was created.
url URI ro URI reference for the asset.
public Boolean ro Indicates whether the asset is in the Skytap public library.
size integer ro Size (in bytes).
owner string wo Used to change the asset owner (see Change asset owner).
owner_url URI ro Asset owner’s user-ref . This field does not exist for Skytap-owned public assets.
owner_name string ro Asset owner’s first and last name, as displayed in the UI. This field does not exist for Skytap-owned public assets.
owner_id string ro Asset owner’s ID number. This field does not exist for Skytap-owned public assets.
can_modify Boolean ro The user’s permissions relative to this asset. These permissions are 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 cannot be modified.
can_delete Boolean ro The user’s permissions relative to this asset. These permissions are 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 cannot be modified.
can_share Boolean ro The user’s permissions relative to this asset. These permissions are 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 cannot be modified.
can_tag Boolean ro The user’s permissions relative to this asset. These permissions are 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 cannot be modified.
tags array ro Array of tags attached to the asset. To add or remove asset tags, see Asset tags sub-resource..
region string ro Region where the asset is housed (for example, us-west).

Assets v2 sub-resources

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

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 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

scope

string

Filters results by asset ownership. Scope options:

  • me: returns all assets owned by the user.
  • company: returns all assets owned by the user or shared with the user through projects.
  • public: returns all Skytap-owned public assets.
  • all: returns all assets that the user has access to. For admins, this includes all assets in the account.

query

string

Name Description
name Filters results by keyword (e.g., iso).
region Filters results by region: US-West, US-Central,US-East, US-East-2, EMEA, APAC, AUS-Sydney, or CAN-Toronto
user_id Filters results by asset owner (for example, 67890). Limited to one user_id per request. This option is not available if the scope parameter is me or public.
extension Filters results by file extension (for example, iso, gz, jpg).

created_at

string

Filters by asset creation date. Options:

  • In the past x hours: now-xh+to+now
  • In the past x days: now-xd+to+now
  • In the past x months: now-xm+to+now
  • Not in the past x days: to+now-xd
  • Custom: timestamp+to+timestamp
Response

Returns a list of assets. Data within the assets is not returned.

Change asset owner

Request

PUT https://cloud.skytap.com/v2/assets/<asset-id>

{
    "owner": "1234"
}

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 does not have the correct permissions or enough storage to own the asset.

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 is 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:

  1. Parse the response body from the POST request to locate the report URL.
  2. Poll the report until the ready field equals true.

    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"
    }
    
  3. 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/v2/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 are not 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.

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

Add tag(s) to the asset

Request

PUT https://cloud.skytap.com/v2/assets/<asset-id>/tags.json

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

Required: One or more values, entered as an array of objects.

Response

Updated list of tags attached to the asset. 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.

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

Add tag(s) to multiple assets

Request

PUT https://cloud.skytap.com/v2/assets/<asset-id-1>,<asset-id-2>/tags.json

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

Required: One or more values, entered as an array of objects.

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.
{
    "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 will not 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.

[
    {
        "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.
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 asset labels

Get asset labels

Request

GET https://cloud.skytap.com/v2/assets/<asset-id>/labels.json

  • 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 are not 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

[
  {
    "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 label(s) to asset

Request

PUT https://cloud.skytap.com/v2/assets/<asset-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.

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 cannot 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.

[
  {
    "id": "121",
    "value": "Operations",
    "label_category": "Team",
    "label_category_id": "123452"
  }
]

Add label(s) to multiple assets

Request

PUT https://cloud.skytap.com/v2/assets/<asset-id-1>,<asset-id-2>/labels.json

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

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.
{
  "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 cannot 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 will not be deleted; it will still be available for reporting.

Response

Updated representation of the labels sub-resource.

Classes v2 resource

For more information about resources enabled in the Skytap Cloud Classrooms extension, see the Classrooms extension REST API reference.

Class labs v2 resource

For more information about resources enabled in the Skytap Cloud Classrooms extension, see the Classrooms extension REST API reference.

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
id integer ro ID assigned to the container by Skytap Cloud
cid string ro ID assigned to the container by Docker
name string rw Container name. Restricted to uppercase letters, lowercase letters, numbers, underscores (_), and periods.
image string ro Docker image the container is based on
created_at timestamp ro Date and time the VM Agent recognized the container
last_run timestamp ro Date and time the container was last run or null if the container has not yet been run.
can_delete Boolean ro The current user’s permissions relative to this container
can_change_state Boolean ro  
status string ro Current status of the container. One of: busy, created, running, restarting, paused, exited, dead, or error.
privileged Boolean ro If true, the container has super privileges on the VM container host. null if the container has not yet been run.
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
configuration_id integer ro Environment ID for the VM container host and container
spawned_at timestamp ro Date and time the container was created on the VM
finished_at timestamp ro Date and time the container was last stopped or exited
error string ro Description of any errors.
command string ro Displays any Docker commands (for example , “nginx -g daemon off;”).
entry_point string ro ENTRYPOINT command executed when the container starts
labels dictionary ro Docker metadata labels attached to this container. Represented as key/value pairs.
ip_address string ro IP address of the container
ports array ro Port bindings for the container
container_links array ro Links to other containers
mounts array ro Filesystem mounts for the container

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/<container-id>.json

Response

The API will return a detailed, read-only representation of the container.

{
    "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/<container-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 does not exist
409 VM agent is not responding, container does not exist (it was 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.
{
    "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. Restricted to uppercase letters, lowercase letters, numbers, underscores (_), and periods.

Response

Updated representation of the container.

{
    "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\nApache CouchDB 1.6.1 (LogLevel=info) is starting.\r\nApache 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\nWARNING: 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\nApache CouchDB 1.6.1 (LogLevel=info) is starting.\r\nApache 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.

{
    "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 Cloud

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 parameters

  • container_registry_id: ID of a container registry from the Skytap Cloud container registries resource.
  • repository: Name of the repository in the container registry.

Optional parameters

  • tag: ID of a container registry from the Skytap Cloud 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.
{
    "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
id integer ro ID assigned to the container registry by Skytap Cloud.
url string ro URL of the container registry in Skytap Cloud.
name string rw Container registry name.
server string rw Host (and optional port) of the container registry server.
email string rw Email address of the container registry user.
username string rw Username of the container registry user.
password string wo Optional password associated with the container registry user.
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.
If false, the password field is set to null or an empty string.
readonly Boolean ro true for Docker public registry.false for all other container registries.
false for all other container registries.
enabled Boolean rw If true, the container registry is enabled for use by users in the account.
updated_at timestamp ro Date and time the container registry was last updated.
last_updated_by object ro Representation of the user who last updated the container registry.
null for Docker public registry entry.

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.

{
    "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.

[
    {
        "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 parameters

  • name: Name of the registry.
  • server: Host (and optional port) of container registry server.

Optional parameters

  • email: Email address of container registry user.
  • username: Username 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 is not included in the request body, the password is set to null.
  • enabled: Either true or false. If not specified, this will be set to true.
Response

Representation of the new container registry.

{
    "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 is 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:

  1. Parse the response body from the POST request to locate the report ID.
  2. Poll the report until the ready field equals true.

    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"
    }
    
  3. 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/v2/container_registries/exports/123456.csv

Response

The report is downloaded.

Courses v2 resource

For more information about resources enabled in the Skytap Cloud Classrooms extension, see the Classrooms extension REST API reference.

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

You must be a Skytap Cloud administrator to access the Departments resource.

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
id integer ro Unique ID of department
url string ro Link to department’s details page
name string rw Descriptive name of the department
description string rw Optional description of department
created_at string ro Date the department was created
updated_at string ro Date the department was last updated
user_count integer ro Number of users in the department
last_updated_by object ro Representation of the user who last updated 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

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

Description

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 parameters

name: Department name

Optional parameters

description: Department description

Response

Representation of the new department

{
    "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

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 login date: last_login or last_login_desc
  • Sort by user account role: account_role or account_role_desc

activated

Boolean

Filters by the user’s account activation status. If true, the user account has been activated.

last_login

string

Filters by user’s last login. Options:

  • In the past x hours: now-xh+to+now
  • In the past x days: now-xd+to+now
  • In the past x months: now-xm+to+now
  • Not in the past x days: 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.

Name Description
account_role Filters results to display users in a specific user role. Options: admin, user_manager, standard_user, or restricted_user
group_id 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 are not in a project, use none.
Response

Representation of department users.

Add user(s) to department

Request

POST https://cloud.skytap.com/v2/departments/<department-id>/users/<user-id>.json

or

POST https://cloud.skytap.com/v2/departments/<department-id>/users.json

{
    "user_ids": "123,124"
}
Response

Representation of added user(s).

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.

[
    {
        "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 user(s) from department

Request

DELETE https://cloud.skytap.com/v2/departments/<department-id>/users/<user-id>

or

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 does not delete the user(s).

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.

id: One of concurrent_svms, concurrent_svms_power, concurrent_vms, storage, or svm_hours. The svm_hours_power quota cannot 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 is 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:

  1. Parse the response body from the POST request to locate the report ID.
  2. Poll the report until the ready field equals true.

    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"
    }
    
  3. 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/v2/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 Cloud 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
id integer ro Unique ID of group
url string ro Link to group’s details page
name string rw Descriptive name of the group
description string rw Optional description of 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
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

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

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

query

string

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

Name Description
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.
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 parameters

name: Group name

Optional parameters

description: Group description

Response

Representation of new group.

{
    "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.

{
    "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/v2/groups/exports

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

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/v2/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:

  1. Parse the response body from the POST request to locate the report URL.
  2. Poll the report until the ready field equals true.

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

    {
       "id": "123456",
       "ready": true,
       "url": "https://cloud.skytap.com/v2/groups/exports/123456",
       "notify_by_email": true,
       "email": "user@internet.net"
    }
    
  3. 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/v2/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
id string ro Identifier
status string ro Status of the tunnel
source_network network rw Source network from where the connection was initiated. This network does not need to be “tunnelable” (visible to other networks).
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).
error string ro Describes any errors with the ICNR connection

Operations on v2 ICNR tunnels

Get tunnel description

Request

GET https://cloud.skytap.com/v2/tunnels/<tunnel-id>.json

Response

Identified tunnel resource

{
    "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
}

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).

source_network_id and target_network_id cannot be the same.

If the source network is a manual network, it cannot be connected to a NAT-enabled network

Response

Representation of the new tunnel.

{
    "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
id integer ro Label identifier
value string ro Name of the label
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
counts list ro Displays the number of labels in that category attached to environments, templates, assets and schedules in the account.

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

  • 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 are not defined, the API will return 1000 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.

[
    {
        "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:

Label categories v2 resource

Each label is nested in a top-level label_categories resource, which is managed by the account administrator(s).

Label categories reference URI

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

Labels resource model

Field Name Type Access Description
id integer ro Label category identifier
name string rw Name of the label category.
Restrictions:- Maximum of 128 characters- The name cannot start with “Skytap:”- The name cannot contain semicolons (;)- You cannot reuse a category name that already exists or existed (even if that category has been deleted)
enabled Boolean rw If true, the label category is enabled and available for use.
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 cannot be changed after the label category is created.
counts list ro Number of environments, templates, assets, and schedules a label in that label category has been applied to.

Operations on v2 label categories

Get label categories

Request

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

Optional parameters
  • By default, Skytap Cloud will hide disabled label categories from the response. To show disabled label categories, include a show_disabled=true query parameter.
  • 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.

  • sort: Sorts the results either in ascending or descending order.

    Options:

    • 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 are not 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.

[
    {
        "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 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

{
    "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

{
    "name": "Customer",
    "id": "123456",
    "enabled": false,
    "single_value": true,
    "counts": {
        "environments": 0,
        "templates": 0,
        "schedules": 0,
        "assets": 0
    }
}

Delete label category

Label categories cannot 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

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

id

string

ro

Unique identifier for a notification rule

rule_type

string

rw

The following is the list of supported notification rule types and the events being monitored for each type:

  • SVMHoursNotificationRule: SVM 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 SVMs usage against account, department, or user limits (as defined in the scope)
  • ConcurrentPowerVMNotificationRule: Concurrent Power SVMs 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

rw

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 subscription.

scope

string

rw

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 are not valid for every rule type. See the table below.

subjects

subjects[]

rw

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 Cloud 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

recipients[]

rw

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)
  • id: 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

ro

Used internally by Skytap Cloud. Do not 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 X X X X X X        
StorageNotificationRule X X X X X X X X X X
ConcurrentVMNotificationRule X X X X X X X X X X
ConcurrentPowerVMNotificationRule X X X X X X X X X X
IPAddressesUsedNotificationRule   X           X   X
NetworksUsedNotificationRule   X           X   X
VMUptimeNotificationRule     X X            

Additionally…

  • customer-quota and customer-limit scopes are valid for monitoring SVM hours in all accounts, and for monitoring concurrent SVM, 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 SVM, 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.

{
    "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.

[
    {
        "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.
  • scope: 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 subject(s) being monitored.
  • recipients: Include the id and type of the users who are notified when the event occurs.

You must be an administrator to perform this action.

Response

Status and the new rule in the response body.

{
    "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 his or her personal SVM 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

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

id

string

ro

Unique identifier for a notification rule

rule_type

string

rw

The following is the list of supported notification rule types and the events being monitored for each type:

  • SVMHoursNotificationRule: SVM hours usage against the user limit
  • StorageNotificationRule: Storage usage against the user limit
  • ConcurrentVMNotificationRule: Concurrent x86 SVMs usage against the user limit
  • ConcurrentPowerVMNotificationRule: Concurrent Power SVMs 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

rw

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

ro

Used internally by Skytap Cloud. Do not 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.

{
    "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.

[
    {
        "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
  • threshold_amount

For a description of these parameters, see the Notifications resource model above.

Response

Status and the new rule in the response body.

{
    "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
id integer ro Identifier
url URI ro URI reference for resource
name string rw User-defined project name
summary string rw User-defined description of project
auto_add_role_name string rw If set to viewer, participant, editor, or manager, Skytap will assign the specified project role to every new user added to the project. The project role roles of existing project members will be unchanged. If auto-add is disabled, this field will be null.
show_project_members Boolean rw Determines whether projects members can view a list of other project members
created_at timestamp ro Date and time that the project was created
owner_name string ro Name of the user who owns the project
owner_url URI ro URI of the user who owns the project
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
can_edit Boolean ro If true, the user viewing the project can edit it.
configuration_count integer ro Number of environments in the project
template_count integer ro Number of templates in the project
users array rw Array of users who are members of the project. Includes each user’s project role (role).

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

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 is not available if the scope parameter is me. Example: query=user_id:67890.

created_at

string

Filters by project creation date. Options:

  • In the past x hours: now-xh+to+now
  • In the past x days: now-xd+to+now
  • In the past x months: now-xm+to+now
  • Not in the past x days: 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>

GET https://cloud.skytap.com/v2/projects/<project-id>/groups/<group-id>

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
id string ro ID of the public IP address (same as address)
address string ro Unique IPv4 public IP address
region string ro Region that the resource is housed in (for example, US-West)
nics array ro Representation of attached network adapter(s), if any. Includes network adapter id and deployed status. This field is only visible to admins.
nic_count integer ro Number of attached network adapters
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.
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

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

Name Description
region Filters results by region (for example: query=region:US-West)
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)

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"
}

region: One of US-West, US-Central, US-East, EMEA, APAC, AUS-Sydney, or CAN-Toronto.

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.

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
id string ro Unique identifier for schedule
url string ro Full URL for schedule
title string rw User-defined name of the schedule. Limited to 256 characters.
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 &amp;amp; Canada). For a list of time zones, see Time Zones and UTC Offsets.
start_at string rw 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.
end_at string rw 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.
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.
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 is not enabled.
executions executions[] ro 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 NameTypeDescription
idstringThe execution's ID
urlstringThe execution's reference URL
schedule_idstringID of the schedule execution belongs to
schedule_urlstringURL of same schedule
configuration_idstringID of environment that the executions affects
configuration_urlstringURL of environment that the executions affects
next_actionobjectA structure that details the target and scheduled time of the next action that will take place as part of the execution
user_idstringThis will display the ID of the execution's owner if that owner is an administrator; otherwise, it will be blank.
user_urlstringThis will display the URL of the execution's owner if that owner is an administrator; otherwise, it will be blank.
recurring_days recurring_days[] rw 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.
actions actions[] rw Array of objects comprising all schedules actions in a schedule, with the exception of actions that cannot recur (i.e., the creation or deletion of environments). Each object has two attributes:
  • Type A string that is one of the legal action types: run, suspend, shut down, power off, and 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 2 hours after the schedule was executed, the offset would be 7200.
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 has not 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.
user object ro 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
region string ro Region that the resource is housed in (for example, US-West)

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_url string ro The URL of the environment the schedule is applied to, ending with the ID number. If the ID is 123, the URL will https://cloud.skytap.com/v2/configurations/123.
configuration_name string ro A string representing the name of the environment the schedule is applied to.

Template fields

These fields only apply to schedules operating on templates.

Field Name Type Access Description
template_id string ro The numerical ID of the template that the schedule is applied to.
template_url string ro The URL of the template the schedule is applied to, ending with the ID number (e.g., https://cloud.skytap.com/v2/templates/123).
template_name string ro User-defined name of the template the schedule is applied to.
new_configuration_name string rw Name of the environment that will be created from the target template once the schedule is started.
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.
vm_ids vm_ids[] rw List 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:

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

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

Name Description
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": "suspend",
                "offset": "7200"
            }
        ],
    "start_at": "2013/09/09 09:00",
    "time_zone": "Pacific Time (US & Canada)"
}
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 would like to assign actions to the schedule during the POST, include an actions array, with type and offset defined.

  • type: One of run, suspend, shut down, power off, and save
  • offset:The number of seconds after start that this action will take place

In XML, you must specify a type attribute of “array” for Actions (<actions type = "array">…</actions>). Specifying this type is not necessary for JSON.

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
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 schedule labels

Get schedule labels

Request

GET https://cloud.skytap.com/v2/schedules/<schedule-id>/labels.json

  • 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 are not 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

[
    {
        "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 label(s) 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

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 cannot 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.

[
    {
        "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 label(s) to multiple schedules

Request

PUT https://cloud.skytap.com/v2/schedules/<schedule-id-1>,<schedule-id-2>/labels.json

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

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.
{
    "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 cannot 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 will not 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

id

integer

ro

ID of the tag

value

string

ro

Tag value. If two or more tags have the same value (across all environments, templates, and assets), they will share the same ID. Tag values are not case-sensitive (for example, test, Test, and TEST will share the same ID).

counts

list

ro

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

Operations on v2 tags

List tags in the account

Request

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

This request can be made by any user or administrator.

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, Skytap will show all tags (even those that are not in use). To show only tags associated with one or more environments, templates, or assets, include a in_use=true query parameter.

GET https://cloud.skytap.com/v2/tags?count=20&offset=0&in_use=true

Response

Representation of tags in the account.

[
    {
        "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:

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

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:

Field Name Type Access Description
id integer ro ID of usage report
start_date
end_date
strings 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.
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.
resource_type string rw Type of resource usage to report on.
One of storage , svms, or svms_power:
  • storage: Storage usage will be reported.
  • svms: Cumulative SVM usage and max concurrent SVM usage for x86 VMs will be reported. svms is the default.
  • svms_power: Cumulative SVM usage and max concurrent SVM usage for Power VMs will be reported.
region string rw Region to report usage on (for example, US-West). all is the default.
label_type string rw 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.
group_by string rw How usage data is grouped.
One of user, group, region, or raw.
user is the default.
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.
results_format string rw File format of the report. One of csv or json.
ready Boolean ro If true, the report is ready for access.
url string ro URL where the report can be accessed.
notify_by_email Boolean rw If true, the report will be emailed to you when it is complete (CSV report only).
error string ro Describes any errors with the report.
email string ro Email address the report will be sent to; this is the email address of the API user.

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:

  1. Parse the response body from the POST request to locate the report ID.
  2. Poll the report until the ready field equals true.

    Check the response body to make sure than an error field is not returned.

    GET https://cloud.skytap.com/v2/reports/<report-id>.json

    (abridged response body):

    
    {
       "id": "123456",
       "ready": true,
       "start_date": "2015/01/28 16:00:00 -0800",
       ...
       "url": "https://cloud.skytap.com/v2/reports/123456.csv",
       "notify_by_email": true,
       "email": "user@internet.net"
    }
    
  3. 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/v2/reports/<report-id>.csv

Response

The report is downloaded.

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

{
    "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.

{
    "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": []
            },
            {...}
        ]
    }
}

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

Users v2 resource

Users are top-level elements in the API data model.

You must be a Skytap Cloud administrator or user manager to create and manage users.

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
id string ro Identifier
url URI ro URI reference for the user
login_name string rw Login 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 ********** (10 asterisks).
If ********** is sent as the value of the password element, it is ignored; the current password will not be changed.
first_name
last_name
strings rw First and last name strings used for display in the UI. Not validated for uniqueness.
title string rw Optional text field for user title
email string rw Email address to which notifications may be sent. Not validated at submit time.
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.
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.
last_login timestamp ro The date and time that the user last logged in
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 Cloud user account; if set to true, the account will use SSO to sign in to Skytap Cloud.
department_name string ro The name of the Skytap Cloud department that the user belongs to. This field is null if the user is not a member of a department.
department_id integer ro The ID of the Skytap Cloud department that the user belongs to. This field is null if the user is not a member of a department.

Because the v2 API does not 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

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.

Name Description
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 are not 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 are not 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 login. Options:

  • In the past x hours: now-xh+to+now
  • In the past x days: now-xd+to+now
  • In the past x months: now-xm+to+now
  • Not in the past x days: 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 will not 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:

Field 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 cannot 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

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.
{
    "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:

  1. Parse the response body from the POST request to locate the report ID.
  2. Poll the report until the ready field equals true.

    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"
    }
    
  3. 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/v2/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
id string ro Reference ID for the export job
ftp_user_name string ro User name for FTP login
ftp_password string ro Password for FTP login
ftp_host string ro Host name of FTP
ftp_url string ro Download location for VM image
template_name string ro Name of source template
vm_name string ro Name of source VM
status string ro Can equal one of four states:
  • new: The status will be new upon initial creation.
  • processing: The VM is being exported.
  • error: If an error occurs, the status will read error and the error will be detailed in the errors field (below).
  • complete: When the export is complete, the status will read complete.
errors string ro Describes the error (when status contains error)
filename string ro File name created by Skytap, present in FTP URL
expiration_date string ro Date when export job will be deleted
template_url string ro URL of source template
vm_url string ro URL of source VM
user string ro Array representing a user, same as in “import” resource

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"
}

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 Cloud 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 Cloud environment. If no networks are defined, Skytap Cloud creates a single automatic network for the environment.

Importing is a multi-step process:

  1. Create a New Import Job
  2. Upload the VM file(s) to the Skytap Cloud SFTP depot. This is done outside of the API using an SFTP client. You will be given the SFTP depot’s hostname and access credentials in the response body for the request to create a new import job
  3. Start the Import
  4. 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
id string ro Reference ID for import job
ftp_user_name string ro User name for SFTP login
ftp_password string ro Password for SFTP login
ftp_host string ro SFTP host name
ftp_url string ro The full SFTP path to the upload repo: sftp://<sftp-username-ref><sftp-password-ref>@<hostname-ref>/upload/
template_name string rw Name of environment to be created; required for all imports
configuration_url string ro This field does not exist until the “status” field equals “complete.” At this point, this field will contain the URL for the new Skytap environment.
status string rw 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.
errors string ro Describes general import error(s) (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
user string ro An array defining the user who created the import. Includes:
  • id
  • url
  • login_name
  • first_name
  • last_name
region string rw Region where the template will be stored. One of US-West, US-Central,US-East, US-East-2, EMEA, APAC, AUS-Sydney, or CAN-Toronto. 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 rw 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)
vms array ro 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 parameters
  • template name: Name of the new environment
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 Cloud checks that the region supports Power VMs; Skytap Cloud presents an error prior to processing the import if Power VMs are not supported in that region.
Response

Representation of the new import, including the hostname, username, and password needed to upload the VM file(s) to the SFTP server.

Start the import

Request

After uploading the VM file(s) 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 depot will be deleted from Skytap’s SFTP server. The environment created from the import will not 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 Cloud account to another network over the public Internet.
  • Private Network Connection: a Private Network Connection is a private, direct network connection between an external network and a Skytap Cloud data center.

WANs are commonly used to connect a network in your organization’s data center to the virtual networks in your Skytap Cloud environments.

Notes

  • At this time, the API supports create, read, update, and delete actions on VPNs, and limited view and edit actions on Private Network Connections. For help with creating or editing a Private Network 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:

  1. Create a VPN
  2. Test the VPN
  3. Enable the VPN

Connecting a virtual network to a VPN or Private Network Connection is a multi-step process:

  1. Attach a network to a VPN or Private Network Connection
  2. Connect the attached network to a VPN or Private Network Connection

WANs v2 reference URI

https://cloud.skytap.com/v2/vpns/<vpn-id>

Notes

  • Throughout the Skytap Cloud API, WANs are referred to as VPNs. Skytap has modified the VPNs resource to include both VPNs and Private Network Connections.
  • The VPN or Private Network Connection’s ID number includes vpn-.

WANs v2 resource model

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

Most of these fields are read-only for Private Network Connections.

Field Name Type Access Description
id string ro Identifier, in the form vpn-#
name string rw User-defined name for the VPN or Private Network Connection. Limited to 255 characters. UTF-8 character type.
url string ro URI for the VPN or Private Network Connection
status string ro Status of the VPN tunnel (inactive or active)
enabled Boolean rw for VPNs, ro for PNCs If true, the VPN or Private Network Connection is enabled
remote_subnets array ro List of remote subnets included or excluded from the VPN or Private Network Connection.
  • 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 NameTypeDescription
idstringThe 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)
cidr_blockstringThe IP range of the subnet.
excludedBooleanIf set to false, this string specifies an included subnet; if set to true, it specifies an excluded subnet.

The / character in the subnet ID and CIDR block will be escaped to %2F in URLs returned by the API.

local_subnet string rw for VPNs, ro for PNCs Range of Skytap IP addresses routed through tunnel.
IPv4 address range.
nat_local_subnet Boolean rw for VPNs, ro for PNCs If true, the VPN or Private Network Connection is NAT-enabled
route_based Boolean rw for VPNs, ro for PNCs If true, the VPN or Private Network Connection is route-based
If false, it is policy-based
nat_pool_size integer ro Total size of IP pool for NAT

Only appears if nat_local_subnet is true

nat_pool_remaining integer ro Remaining assignable IP addresses for NAT

Only appears if nat_local_subnet is true

local_peer_ip string rw for VPNs, ro for PNCs Public IPv4 address associated with the VPN or Private Network Connection (must be an available Skytap public IP address)

Only visible to administrators

remote_peer_ip string rw for VPNs, ro for PNCs Public IPv4 address associated with VPN or Private Network Connection endpoint on external network

Only visible to administrators

attached_network_count integer ro Number of networks attached to VPN or Private Network Connection

Only visible to administrators

connected_network_count integer ro Number of networks connected to VPN or Private Network Connection

Only visible to administrators

network_attachments array ro Representations of the relationships between this VPN or Private Network Connection and any network(s) 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/&amp;lt;vpn-id&amp;gt;
Related: Network v2 Resource.

Only visible to administrators

test_results collection ro Results of 4 tests: Connect, Phase1, Phase2, and Ping

Only visible to administrators. Always null for Virtual Private Networks

phase_1_encryption_algorithm string rw for VPNs, ro for PNCs Phase 1 encryption algorithm. One of 3des, aes, or aes 256.

Only visible to administrators

phase_1_hash_algorithm string rw for VPNs, ro for PNCs Phase 1 hash algorithm. One of md5 or sha1.

Only visible to administrators

phase_1_sa_lifetime integer rw for VPNs, ro for PNCs Value in seconds of Phase 1 SA lifetime. Valid range: 1 to 2147483647.

Only visible to administrators

phase_1_dh_group string rw for VPNs, ro for PNCs Phase 1 Diffie-Hellman Group
One of modp1024 or modp1536.

Only visible to administrators

phase_1_pre_shared_key string wo for VPNs, N/A for PNCs Phase 1 pre-shared key

Only visible to administrators

phase_2_encryption_algorithm string rw for VPNs, ro for PNCs Phase 2 encryption algorithm. One of 3des, aes, aes 256, or aes_gcm.

Only visible to administrators

phase_2_authentication_algorithm string rw for VPNs, ro for PNCs Phase 2 authentication algorithm. One of hmac_md5 or hmac_sha1.

Only visible to administrators

phase_2_perfect_forward_secrecy Boolean rw for VPNs, ro for PNCs If true, Perfect Forward Secrecy (PFS) is used

Only visible to administrators

phase_2_pfs_group strings rw for VPNs, ro for PNCs Shows name of PFS group if Phase 2 PFS is set to true.

One of modp1024 or modp1536.

Only visible to administrators

phase_2_sa_lifetime integer rw for VPNs, ro for PNCs Value (in seconds) of Phase 2 SA Lifetime. Valid range: 1 to 2147483647.

Only visible to administrators

sa_policy_level string rw for VPNs, ro for PNCs Security policy level, the options are null, require, or unique

Only visible to administrators

The use SA policy level was deprecated in March 2016.

maximum_segment_size string rw for VPNs, ro for PNCs 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.

Only visible to administrators

dpd_enabled Boolean rw for VPNs, ro for PNCs If true, Dead Peer Detection is enabled

Only visible to administrators

region string ro Skytap Cloud region (for example: US-West).

Only visible to administrators

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

Only visible to administrators

error string ro If there is an error, this field will contain information about the error. Otherwise, this field will be blank.

Only visible to administrators

default_access_level string ro One of:
  • use: All users in your account can use this VPN or Private Network Connection.
  • null: By default, only administrators in your account can use this VPN or Private Network Connection. 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/&amp;lt;vpn-id&amp;gt;/acl (see below).
acl object rw Array describing the access control list for the VPN or Private Network Connection. This array will not 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/&amp;lt;vpn-id&amp;gt;/acl

Only visible to administrators

Field NameTypeDescription
default_access_levelstring(rw)One of two options:
  • use: All users in your account can use this VPN or Private Network Connection.
  • null: By default, only administrators in your account can use this VPN or Private Network Connection. You can grant additional custom access to individual users, groups, or departments.
grantee_countsobject(ro)Contains:
  • totals: Contains:
    • users: Number of users granted custom access to the VPN or Private Network Connection
    • groups: Number of groups granted custom access to the VPN or Private Network Connection
    • departments: Number of departments granted custom access to the VPN

These numbers do not include users, groups, or departments that inherit access from the default access level setting.

connection_type string ro Type of WAN. Either vpn or direct.
vpn is a Virtual Private Network; direct is a Private Network Connection.

Operations on v2 WAN resources

List VPNs and Private Network Connections

Request

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

Response

Representation of VPNs and Private Network Connections in the account.

Get VPN or Private Network Connection 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 VPN or Private Network Connection.

Create 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",
    "phase_1_encryption_algorithm": "3des",
    "phase_1_hash_algorithm": "md5",
    "phase_1_pre_shared_key": "HelloWorld",
    "phase_1_sa_lifetime": 28800,
    "phase_1_dh_group": "modp1024",
    "phase_2_encryption_algorithm": "3des",
    "phase_2_authentication_algorithm": "hmac_md5",
    "phase_2_perfect_forward_secrecy": false,
    "phase_2_pfs_group": null,
    "phase_2_sa_lifetime": 3600,
    "sa_policy_level": "require",
    "maximum_segment_size": null,
    "dpd_enabled": true
}

Notes

  • You must be an administrator to make this request.
  • You cannot create Private Network Connections from the API.
Response

Representation of the new VPN.

Test a VPN

Request
  1. 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

    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 to check the connection between Skytap and machines on your VPN.

    Optional

    A remote port that is open on the remote machine; if you do not enter a port, no TCP connectivity test is performed.

    Notes

    • You must be an administrator to make this request.
    • You cannot test Private Network 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
    

    or

     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 cannot test Private Network Connections from the API.
Response

Updated VPN resource.

Edit the VPN or Private Network Connection

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.
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 cannot edit the remote subnet for Private Network 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 cannot edit the remote subnet for Private Network 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 cannot edit the remote subnets for Private Network Connections from the API.
Response

Deleted remote subnet

Attach/connect/disconnect/detach a virtual network to a VPN or Private Network Connection

To attach, connect, disconnect, or detach a network to a VPN or Private Network Connection, edit the Networks resource. For instructions, see Network v2 Resource.

View a summary of the access control list for a VPN or Private Network Connection

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.

{
    "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"
}

default_access_level: One of use or null.

This request can only be made by administrators.

Response

Updated representation of the VPN or Private Network Connection access control list.

{
    "default_access_level": "use",
    "grantee_counts": {
        "totals": {
            "users": 0,
            "groups": 0,
            "departments": 0
        }
    }
}

View the users, groups, or departments with custom access to the VPN or Private Network Connection

Request

GET https://cloud.skytap.com/v2/vpns/<vpn-id>/acl/users.json?count=20&offset=0

or

GET https://cloud.skytap.com/v2/vpns/<vpn-id>/acl/groups.json?count=20&offset=0

or

GET https://cloud.skytap.com/v2/vpns/<vpn-id>/acl/departments.json?count=20&offset=0

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.

[
    {
        "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 VPN access for a user, group, or department

Request

PUT https://cloud.skytap.com/v2/vpns/<vpn-id>/acl/users/<user-id>.json

or

PUT https://cloud.skytap.com/v2/vpns/<vpn-id>/acl/groups/<group-id>.json

or

PUT https://cloud.skytap.com/v2/vpns/<vpn-id>/acl/departments/<department-id>.json

{
    "access_level": "use"
}

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.

{
    "type": "Group",
    "id": 123,
    "name": "QA",
    "description": "QA Group",
    "access_levels": [
        "use"
    ]
}

Remove VPN or Private Network Connection access for a user, group, or department

Request

DELETE https://cloud.skytap.com/v2/vpns/<vpn-id>/acl/users/<user-id>.json

or

DELETE https://cloud.skytap.com/v2/vpns/<vpn-id>/acl/groups/<group-id>.json

or

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.

{
    "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 cannot delete Private Network Connections from the API.
Response

Deleted VPN.

v2 change log

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 do not 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

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 backwards-compatibility, the reference URI has not 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. For more information, see Classrooms extension REST API reference.

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 quota types to user, department, and account limits. The svm_hours_power quota cannot be edited.
    • Added svms_by_architecture attribute to environment and template resource models.
    • Added notes that some VM hardware attributes cannot be edited and are not 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 cannot 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 cannot 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 Cloud 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

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

October 2016

August 2016

July 2016

June 2016

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 FTP 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 have not 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 will be now 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. This change does not affect customers who do not 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 backwards-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

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:

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 will not 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

August 2015

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.