API v1 reference

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

For general information about using the API, see Skytap REST API and Skytap API quick start.

Date and time formatting

The API accepts dates in multiple standard formats:

  • Dates are exposed in the API as YYYY/MM/dd HH:mm:ss
  • We also accept the ISO 8601 format (2018-03-21T01:00:00.000Z).

The number of digits is fixed; single-digit dates or months must be preceded by zeroes (for example, 2018/03/09).

Skytap manages time zones symbolically rather than simply by offset from UTC. For a list of time zones, see Time zones and UTC offsets.

Resources

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

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

Environments resource

> Environment VMs

> VM credentials

> VM metadata

> VM labels

> VM notes

> VM network adapters

> Published services

> Secondary IP addresses

> Environment Multi-Attach Storage

> Environment networks

> Environment notes

> Environment sharing portals

> Environment VM sequencing stages

Templates resource

> Template VMs

> VM credentials

> VM metadata

> VM labels

> VM notes

> VM network adapters

> Published services

> Template networks

> Template labels

> Template sharing portals

> Template VM sequencing stages

Account limits resource

Assets resource

Auditing reports resource

Departments resource

Groups resource

Inter-Configuration Network Routes (‘Tunnels’) resource

Notification rules resource (account-wide)

Notification rules resource (user-defined)

Projects resource

Public IPs resource

Schedules resource

Usage reports resource

Users resource

VM exports resource

VM imports resource

WANs resource

Webhooks resource

Environments 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 reference URI

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

Environments resource model

The element name is configurations.

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

The following fields are defined:

Field Name Type Access Description
cidr_block integer ro Shows IP range that associated networks must be housed within.
description string rw User-defined description of the environment. Limited to 1000 characters. Null allowed. UTF-8 character type.
disable_internet Boolean rw If true, outbound internet is disabled for VMs in this environment. Note that VMs with public IPs or published services will still be exposed to the Internet.
environment_locked Boolean rw If true, the environment is locked to prevent changes or deletion. Only the environment owner or an administrator can change this value.
error string ro Describes any errors with the environment.
id string ro Environment identifier.
name string rw User-defined name of the environment. Limited to 255 characters. UTF-8 character type. Defaults to source template’s name if null is provided.
networks array ro Array of networks in the environment. Every environment can have multiple networks; the number of total networks that can be created is restricted by your customer account’s network usage limit.

Networks are added to this list when they are connected to a network adapter on a VM in the environment. Similarly, networks are removed from this list when they are disconnected from network adapters on VMs in the environment. For more information, see Network Interface Resource
owner URI rw URI reference of the environment’s owner (e.g., https://cloud.skytap.com/users/123456).
platform_errors array ro Array containing information about select errors. Each object contains an incident_id parameter that can be used to troubleshoot issues with the Skytap support team.
prefer_local_routing Boolean rw If true, different subnets within an environment can communicate with each other.
publish_sets array ro Array of published set resources providing anonymous access to VMs within the environment.
rate_limited Boolean ro If true, the environment is being rate-limited due to a high amount of activity in the account. For more information, see API best practice: Checking for busyness.
region string ro Region that the resource is housed in (for example, US-West). The environment will exist in the same region as the template it was created from.
region_backend string ro Region that the resource is housed in (for example, US-West).
routable Boolean rw Indicates whether networks within the environment can route traffic to one another.
runstate string rw Because it can potentially represent the states of many VMs, the ‘runstate’ of an environment is a synthesized value. The environment runstate results should be interpreted as follows:
  • running – one or more VMs are running
  • stopped – all VMs are stopped
  • suspended – one or more VMs are suspended, others are stopped

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

UTF-8 character type.

.
shutdown_at_time timestamp rw The date and time that the environment will be automatically shut down.
If shutdown_on_idle and shutdown_at_time are both null, automatic shut down is disabled.
shutdown_on_idle integer rw The number of seconds an environment can be idle before it’s automatically shut down.
If shutdown_on_idle and shutdown_at_time are both null, automatic shut down is disabled.
suspend_at_time timestamp rw The date and time that the environment will be automatically suspended.
If suspend_on_idle and suspend_at_time are both null, automatic suspend is disabled.
suspend_on_idle integer rw The number of seconds an environment can be idle before it’s automatically suspended.
If suspend_on_idle and suspend_at_time are both null, automatic suspend is disabled.
url URI ro URI reference for the environment.
vms array rw Array of virtual machines in the environment. It is legal to have 0 entries in this array.
The API supports adding elements to the array indirectly by adding VMs to the environment; it also supports deleting entries from the array by a DELETE request on the array member.

Environments 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/configurations/{configuration-id}.json

Response

Representation of the environment.

Get list of environments

Request

GET https://cloud.skytap.com/configurations

Response

Returns a list of environments owned by the user or shared with the user via projects.

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

Get all environments

Request

To compile a list of all of the environments in the account, administrators must make a separate GET request against each user’s ID using GET https://cloud.skytap.com/users/<user-id>. These requests will return a list of environments owned by each user.

Response

Representations of environments in the account.

Create environment

Request

POST https://cloud.skytap.com/configurations.json

{
    "template_id": "12345"
}

Required and optional parameters

Required parameter
template_id ID of the template you want to create an environment from.
Optional parameter
project_id ID of the project you want to add the environment to.
name The name you want for the new environment.
Response

Representation of the new environment

Edit environment

Request

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

Response

Representation of the updated environment

Save environment as template

See instructions for Creating a New Template in Template Resource.

Copy environment

Request

POST https://cloud.skytap.com/configurations.json

{
    "configuration_id": "123456",
    "vm_ids": [
        "888888",
        "222222"
    ],
    "mas_group_ids": [
        "mas-2dF0vXLdtYetYxxjnEygx6vwKlM",
        "mas-2dF0vXLdtYetYxxjnEyawdcmklp"
    ]
}

Required and optional parameters

Required parameter
configuration_id ID of the environment being copied.
Optional parameters
live_copy Copy running VMs without suspending them. We recommend that you quiesce VM activity on running VMs before you copy them. Either true or false.
vm_ids Array of the VMs you want to copy. If specified, only these VMs and their connected networks will be copied to the new environment.
mas_group_ids Array of the multi-attach storage groups you want to copy.
Response

If successful, returns a new copy of the specified environment. Returns a 409 error if the environment contains one or more running Power VMs; these can’t be suspended. Shut down the Power VMs and retry.

Copy environment to a different region

Request

POST https://cloud.skytap.com/configurations.json

{
    "configuration_id": "123456",
    "target_region": "US-West"
    "resource_mapping": {
        "public_ip": {
            "1.2.3.0": "4.5.6.0"
            },
        "vpn": {
            "vpn-12345": "vpn-67890"
        }
    },
    "vm_ids": [
        "888888",
        "222222"
    ],
    "mas_group_ids": [
        "mas-2dF0vXLdtYetYxxjnEygx6vwKlM",
        "mas-2dF0vXLdtYetYxxjnEyawdcmklp"
    ]
}

Required and optional parameters

Required parameter
configuration_id ID of the environment being copied.
target_region Region where you want the new environment to be hosted. One of APAC-2, AU-Sydney-I-1, CAN-Toronto, CN-HongKong-M-1, DE-Frankfurt-1-1, EMEA, IE-Dublin-M-1, IN-Pune-M-1, NL-Amsterdam-M-1, SG-Singapore-M-1, UK-Londond-M-1, US-Central, US-East-2, US-Texas-M-1, US-Virginia-M-1, or US-West.
Optional parameters
resource_mapping Object that maps VPNs and public IPs in the current region to VPNs and public IPs in the target region.
vm_ids Array of the VMs you want to copy. If specified, only these VMs and their connected networks will be copied to the new environment.
mas_group_ids Array of the multi-attach storage groups you want to copy.
Response

Representation of the new environment in the target region (in this example, US-West).

Change environment owner

Request

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

{
    "owner": "1245"
}

Required and optional parameters

Required parameters
owner ID of the user you want to be the new environment owner. If the user is a restricted user, you must also include reassign_context with the ID of a project that the user has editor or manager privileges in.
Optional parameters
reassign_context Contains a project ID; used to add the environment to a project during ownership reassignment. This parameter is required when reassigning ownership to a restricted user and optional when reassigning ownership to any other user type.
Response

Representation of the updated environment.

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

Change environment runstate

Request

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

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

Runstate options

The following table describes the possible runstate transitions:

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

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

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

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

Response

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

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

Notes

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

Change runstate of some VMs

Request

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

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

Required Parameters

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

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

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

Add VMs

Request

You can add VMs by copying all of the VMs from a template or another environment into the target environment. Or, you can copy select VMs from a template or another environment into the target environment.

To copy a template into the environment:

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

{
    "template_id": "12456"
}

To copy an environment into the environment:

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

{
    "merge_configuration": "123455"
}

To add select VMs, list their VM IDs in the request body:

{
    "template_id": "12456",
    "vm_ids": [
        "999999",
        "111111"
    ],
    "mas_group_ids": [
        "mas-2dF0vXLdtYetYxxjnEygx6vwKlM",
        "mas-2dF0vXLdtYetYxxjnEyawdcmklp"
    ]
}

or

{
    "merge_configuration": "12455",
    "vm_ids": [
        "888888",
        "222222"
    ],
    "mas_group_ids": [
        "mas-2dF0vXLdtYetYxxjnEygx6vwKlM",
        "mas-2dF0vXLdtYetYxxjnEyawdcmklp"
    ]
}

Required and optional parameters

Required parameters

Either template_id or merge_configuration; only one template or environment per request:

template_id ID of the template you want to copy VMs from.
merge_configuration ID of the environment you want to copy VMs from.
Optional parameters
vm_ids Array of the VMs IDs you want to copy.
mas_group_ids Array of the multi-attach storage groups you want to copy.
live_copy Add running VMs without suspending them. We recommend that you quiesce VM activity on running VMs before you copy them. Either true or false.
Response

If successful, returns a representation of the updated environment.

Network interfaces on the VMs are adjusted to the network in the environment, where possible. Other VM elements (metadata, notes, etc.) are discarded.

Returns a 409 error if a running Power VM is included in the array; these can’t be suspended during the add VM process. Shut down the Power VMs and try again.

Enable automatic suspend when the environment is idle

Request

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

{
    "suspend_on_idle": 3600
}
Required parameter
suspend_on_idle The number of seconds the environment should be idle before it automatically suspends. Valid range: 300 to 86400 seconds (5 minutes to 1 day).

Notes

  • An environment can't be set to automatically suspend and shut down. Only one of the following settings can take effect: suspend_on_idle, suspend_at_time, shutdown_on_idle, or shutdown_at_time.
  • When you send a request that updates one of the four suspend or shutdown options, the other three options are automatically set to null by the REST API.
Response

Returns a representation of the updated environment.

Enable automatic shutdown when the environment is idle

Request

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

{
    "shutdown_on_idle": 3600
}
Required parameter
shutdown_on_idle The number of seconds the environment should be idle before it shuts down. Valid range: 300 to 86400 seconds (5 minutes to 1 day).

Notes

  • An environment can't be set to automatically suspend and shut down. Only one of the following settings can take effect: suspend_on_idle, suspend_at_time, shutdown_on_idle, or shutdown_at_time.
  • When you send a request that updates one of the four suspend or shutdown options, the other three options are automatically set to null by the REST API.
Response

Returns updated environment.

Enable automatic suspend for a specific date and time

Request

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

{
    "suspend_at_time": "2018/05/20 14:20:00"
}
Required parameter
suspend_at_time The date and time the environment should be suspended. Format: yyyy/mm/dd hh:mm:ss.

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

Notes

  • An environment can't be set to automatically suspend and shut down. Only one of the following settings can take effect: suspend_on_idle, suspend_at_time, shutdown_on_idle, or shutdown_at_time.
  • When you send a request that updates one of the four suspend or shutdown options, the other three options are automatically set to null by the REST API.
Response

Returns updated environment.

Enable automatic shut down for a specific date and time

Request

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

{
    
    "shutdown_at_time": "2018/05/20 14:20:00"
}
Required parameter
shutdown_at_time The date and time the environment should be shut down. Format: yyyy/mm/dd hh:mm:ss.

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

Notes

  • An environment can't be set to automatically suspend and shut down. Only one of the following settings can take effect: suspend_on_idle, suspend_at_time, shutdown_on_idle, or shutdown_at_time.
  • When you send a request that updates one of the four suspend or shutdown options, the other three options are automatically set to null by the REST API.
Response

Returns updated environment.

Disable automatic suspend

Request

Set suspend_on_idle or suspend_at_time to an empty string (”“).

Example request:

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

{
    "suspend_at_time": ""
}
Response

Returns updated environment.

Disable automatic shut down

Request

Set shutdown_on_idle or shutdown_at_time to an empty string (”“).

Example request:

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

{
    "shutdown_at_time": ""
}
Response

Returns updated environment.

Create Vagrantfile

Request

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

Optional URL Parameters

To customize the Vagrantfile creation, include one or both of the following URL parameters:

include_api_credentials=true The Vagrantfile will contain your account user name and API token.
By default, the Vagrantfile contains <your username> and <your api token> placeholder values.
This parameter will be ignored if you don’t have API tokens enabled in your account.
include_hardware_properties=true The Vagrantfile will include the VMs’ CPU, RAM, and guest OS properties.
By default, these properties are omitted.

The Vagrantfile is retrieved with a standard HTTP request. The response is UTF-8 text.

Response
# This Vagrantfile was generated from the "SharePoint Farm"
# environment: https://cloud.skytap.com/configurations/1234567

Vagrant.configure(2) do |config|
    # The "skytap/empty" box contains minimal metadata. The source VMs
    # are specified below using the vm_url setting.
    config.vm.box = "skytap/empty"

    # Credentials for the Skytap REST API. If you plan to check this
    # Vagrantfile into source control, consider omitting this block,
    # and setting the environment variables VAGRANT_SKYTAP_USERNAME
    # and VAGRANT_SKYTAP_API_TOKEN instead.
    config.vm.provider :skytap do |skytap|
        skytap.username  = "<your username>"
        skytap.api_token = "<your api token>"
    end

    config.vm.define :vm1 do |vm1|
        vm1.vm.provider :skytap do |skytap|
            # VM name: Active Directory Server
            skytap.vm_url = "https://cloud.skytap.com/vms/121212"
        end
    end

    config.vm.define :vm2 do |vm2|
        vm2.vm.provider :skytap do |skytap|
            # VM name: SharePoint Web Tier
            skytap.vm_url = "https://cloud.skytap.com/vms/232323"
        end
    end

end

Delete environment

Request

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

Deleted environments can’t be recovered.

Response

Status only

Delete environments

Request

DELETE https://cloud.skytap.com/configurations/destroy_multiple.json

{
    "multiselect": [
        "123456",
        "123457",
        "123458",
        "123459"
    ]
}

Parameters

multiselect Array of the configuration IDs for the environments that you want to delete.

Deleted environments can’t be recovered.

Response

Status only

Export environments report (.CSV)

Step 1: Create the report

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

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

Initial response

Sample response body:

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

    {
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/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/configurations/exports/123456.csv
Response

The report is downloaded.

Environment VMs resource

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

Note that:

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

Environment VMs reference URI

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

You can optionally specify the containing environment in the URL, but this isn’t required (https://cloud.skytap.com/configurations/<configuration-id>/vms/<vm-id>).

Environment VMs resource model

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

Field Name Type Access Description
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.
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.
configuration_url string ro Location of VM. configuration_url is used for a VM in an environment. template_url is used for a VM in a template.
created_at timestamp ro Date and time the VM was created.
credentials array ro Array of credentials stored on the VM and available from the Credentials page in the UI. Includes text and id values.
To edit this array, see VM credentials sub-resource.
display_server string 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, 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.
The VM must be powered off to change this value.

Not available in all accounts. For more information, see Connection types.
error string ro If there was a fault or failure in performing some operation on the VM, this field will contain some information that will help interpret the error.
error_details object ro Provides details about any errors with the environment.
hardware hardware rw Hardware description. For more information, see Notes on the “hardware” element.
hardware_version integer ro VM hardware version number. Always null for Power.
id string ro VM identifier.
interfaces interface ro Array of virtual network interfaces.
To edit this array, see VM network adapters.
labels array ro Array of labels attached to the VM. Includes type, text, and id values.
To edit this array, see VM labels sub-resource.
lpar_id string ro LPAR ID of the pinned VM. Initially null. After the VM is run, this field is populated with a value that persists, regardless of runstate, until the VM is powered off and unpinned. Always null for x86.
name string rw User-defined name. Limited to 100 characters.

The name will be truncated to 33 UTF-8 characters after saving.
notes array ro Array of notes stored on the VM. Includes text and id values.
To edit this array, see VM notes.
pinning_type string rw Indicates whether and how the VM should be pinned. Initially null until a VM is pinned. Accepted values are hard to pin a VM or null to unpin it. Always null for x86.
power_machine_type string ro Machine type of the Power host for the pinned VM. Initially null. After the VM is run, this field is populated with a value that persists, regardless of runstate, until the VM is powered off and unpinned. Always null for x86.
power_model_number string ro Model number of the Power host for the pinned VM. Initially null. After the VM is run, this field is populated with a value that persists, regardless of runstate, until the VM is powered off and unpinned. Always null for x86.
power_serial_number string ro Serial number of the Power host for the pinned VM. Initially null. After the VM is run, this field is populated with a value that persists, regardless of runstate, until the VM is powered off and unpinned. Always null for x86.
publish_set_refs array 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 doesn’t require a Skytap account.

These references exist only when the enclosing environment has been assigned one or more Published Set resources. If no such resources are defined then the publish_set_refs element won't be returned.
rate_limited Boolean ro Shows if the VM is rate-limited.
region_backend string ro Region that the resource is housed in (for example, US-West).
runstate string rw Runstate of VM. UTF-8 character type. See allowed values in parameters section of Change VM runstate below.
template_url string ro Location of VM. configuration_url is used for a VM in an environment. template_url is used for a VM in a template.
user_data string – user_data** does NOT appear in the normal representation of a VM; it must be requested from its own endpoint. See VM metadata.

Notes on the hardware element

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

Field Name Type Access Description
architecture string ro Either power or x86.
boot_option string ro Either bios or uefi.
copy_paste_enabled Boolean rw If true, copy and paste is enabled between a local machine and the VM (when the VM desktop is accessed via the browser).

Copy/paste for Power is available only for SSH connections.
cpus integer rw Number of CPUs allocated to this virtual machine. Maximum limit depends on the max_cpus setting.

The VM must be powered off to change this value.
cpw integer ro Estimated CPW (Commercial Processor Workload) for IBM i VMs.
cpus_per_socket integer rw (x86)
ro (Power)

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


Specifies how the total number of CPUs should be distributed across virtual sockets. By default cpus_per_socket is set to 1, meaning that a single core is distributed per virtual socket.
To create multi-core CPUs, set a higher number of CPUs per socket. For example, to create two quad-core processors in the VM, use the following settings: {"cpus": 8,"cpus_per_socket": 4}
Notes
  • The VM can't have more than 12 CPUs.
  • The number of CPUs must be evenly divisible by the number of cores per socket (for example, if you have 12 CPUs, the cores per socket must be 1, 2, 3, 4, or 6).
  • Always 1 for Power
disks array rw Array of virtual disks within the VM. The disk size is in MB; it will be converted to GB in the Skytap UI. The maximum disk size is 2,096,128 MB (1.999 TB).
displays integer rw Total number of displays enabled in the SRA browser client. Default is 1. Maximum is max_displays.
entitled_capacity integer ro Total number virtual CPU cores allocated to this VM.
guestOS string rw This field tells the underlying host which operating system the VM is running and whether nested hypervisors are enabled.
guestOS_version string rw This field tells the underlying host which version of the operating system configured in guestOS that the VM is running.
For a complete list of supported guest OS versions, see Supported operating systems for Skytap VMs

guestOS_version applies only to Power VMs.
ibmi_boot_side string rw IPL source. For details about IBM i IPL types, see IPL type.
ibmi_boot_mode string rw IPL mode: normal for unattended, or manual for attended.
ibmi_current_pricing string ro Current pricing plan for this VM. Either hourly or monthly.
ibmi_future_pricing string rw The pricing plan that will be charged for this VM after the end of the current billing cycle. Either hourly or monthly.
ibmi_licenses string ro A list of IBM i licenses in use by this VM. Current valid settings are:
Field NameTypeDescription
ibmi_defaultBooleantrue for licensed IBM i VMs.
ibmi_mimix_integrationBooleantrue if Precisely Assure MIMIX™ Software is enabled for this VM.
ibmi_powerhaBooleantrue if Power HA is enabled for this VM.
developer_licensesintegerNumber of IBM Rational Developer for i licenses enabled for this VM.
instance_type string ro This field is not currently in use. It always returns as null.
max_cpus integer ro Maximum settable CPUs for this VM.
max_displays integer ro Total number of displays that can be enabled in the SRA browser client.
max_ram integer ro Maximum settable RAM for this VM.
maximum_video_ram_enabled Boolean rw If true, multiple-monitor display mode is enabled in the SRA browser client.
min_ram integer ro Minimum settable RAM for this VM.
nested_virtualization Boolean rw (x86)
ro (Power)		 If true, nested virtualization is enabled on the VM. For more information, see Enabling nested virtualization.
Always false for Power.
power_cpu_sharing_mode string rw vCPU sharing mode for Power. Either capped or uncapped. For more information, see Editing VM vCPUs and RAM.

The VM must be powered off to change this value.
ram integer rw Amount of RAM allocated to this VM.
Valid range is 256 and 131,072 (MB). Maximum limit depends on max_ram setting

The VM must be powered off to change this value.
rdp_port string ro Displays a port number, if the VM is configured to allow RDP connections in the SRA browser client over a custom port number.
rtc_start_time Unix timestamp rw (x86)
ro (Power)		 Used to set the VM BIOS clock at boot. Must be a UNIX timestamp (for example, 1456168430 is the Unix timestamp for Feb 22, 2016 7:13 PM UTC) or null (to disable this feature).
You can’t set the rtc_start_time if time-sync is enabled
Always null for Power.
svms integer ro Amount of Metered RAM used by this VM.
storage integer ro Total amount of storage consumed by the VM in MB. Calculated by adding the storage size of all disks within the VM.
supports_multicore Boolean ro Indicates whether the VM supports multi-core CPUs. Currently, multi-core CPUs are only supported for VMs set to hardware version 10 or 11.false for Power.
time_sync_enabled Boolean rw (x86)
ro (Power)		 If true, time-sync is enabled. For more information, see Editing VM hardware and guest OS settings.
Always false for Power.
ssh_port string ro Displays a port number, if the VM is configured to allow SSH connections in the SRA browser client over a custom port number.
uuid integer rw (x86)
ro (Power)		 User-defined, static Universal Unique Identifier (UUID). By default, this field is null; this means that Skytap automatically assigns the UUID. Maximum of 32 hexadecimal characters (0-9, A-F, a-f).
Always null for Power.
upgradable Boolean ro If true, the VM isn’t on the latest supported hardware version; the VM hardware version can be upgraded through the Skytap UI
Always false for Power.
vnc_keymap string rw (x86)
ro (Power)		 Keyboard language mapping (UTF-8). For a list of supported international keyboards and attribute values, see Using an international keyboard with a VM.
Always null for Power.

Environment VM 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/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/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,
    "display_server": null,
    "audio_in": false,
    "audio_out": false,
    "configuration_url": "https://cloud.skytap.com/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/vms/{vm-id}?{attr-name}={attr-value}

Response

Updated VM element

Edit VM hardware settings (for example: CPUs)

Request

PUT https://cloud.skytap.com/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/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,
    "display_server": null,
    "audio_in": false,
    "audio_out": false,
    "configuration_url": "https://cloud.skytap.com/configurations/12345678",
    "publish_set_refs": []
}

Add a disk

Request

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

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

Notes

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

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

{
    "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/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,
    "display_server": null,
    "audio_in": false,
    "audio_out": false,
    "configuration_url": "https://cloud.skytap.com/configurations/12345678",
    "publish_set_refs": []
}

Edit the size of a disk

Request

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

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

Notes

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

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

{
    "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/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,
    "display_server": null,
    "audio_in": false,
    "audio_out": false,
    "configuration_url": "https://cloud.skytap.com/configurations/12345678",
    "publish_set_refs": []
}

Delete a disk

Request

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

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

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

Response

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

{
    "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/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,
    "display_server": null,
    "audio_in": false,
    "audio_out": false,
    "configuration_url": "https://cloud.skytap.com/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/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/vms/{vm-id}?hardware[copy_paste_enabled]=false

Cannot be performed on Power VMs.

Response

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

Enable nested virtualization

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

Request

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

Cannot be performed on Power VMs.

Response

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

Change VM run state

Request

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

{
    "runstate": "running"
}
Required parameters

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

Runstate options

Starting Runstate New Runstate
Running Reset Stopped Halted Suspended
Running No change VM is powered off and then run Graceful shut down Forced shut down Suspended
Stopped Running VM (invalid) No change No change (invalid)
Suspended Running VM (invalid) (invalid) Forced shut down No change
  • Power VMs can’t be suspended.

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

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

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

Response

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

Notes

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

Mount ISO Asset

Request

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

{
    "asset_id": "12345"
}

Required Parameters

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

Response

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

Download VM RDP File

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

Optional Parameters

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

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

Cannot be performed on Power VMs.

Response

One of the following RDP files:

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

Export a network endpoints report (.CSV)

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

Step 1: Create the report

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

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

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/vms/111111/export_network_connections/123456",
    "notify_by_email": true,
    "email": "user@internet.net"
}
Step 2 (Optional): Download the report via the API

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

  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/vms/111111/export_network_connections/123456.json

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

  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/vms/<vm-id>/export_network_connections/<export-id>.csv
Response

The report is downloaded.

Delete VM

Request

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

Deleted VMs can’t be recovered.

Response

Status only

Delete VMs

Request

DELETE https://cloud.skytap.com/configurations/{configuration-id}/vms/destroy_multiple.json

{
    "multiselect": [
        "123456",
        "123457",
        "123458",
        "123459"
    ]
}

Required parameters

multiselect – An array of IDs for the VMs that you want to delete.

Deleted VMs can’t be recovered.

Response

Status only

VM credentials resource

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

VM credentials reference URI

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

VM credentials resource model

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

Operations on VM credentials

Get VM credentials

Request

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

Response

Credentials will be displayed.

Add VM credentials

Request

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

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

Required Parameters

text Credentials in username / password format.

This action isn’t supported for VMs in templates.

Response

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

Edit VM credentials

Request

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

{
    "text": "username / password"
}

Required Parameters

text Credentials in username / password format.

This action isn’t supported for VMs in templates.

Response

Edited credentials will be displayed.

Delete VM credentials

Request

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

This action isn’t supported for VMs in templates.

Response

Status.

VM labels 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 reference URI

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

VM labels resource model

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

Supported operations on VM labels

Get VM labels

Request

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

Response

Representation of the VM labels.

Add VM label

Request

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

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

Required parameters

tag_type Label category name. The label category type must be a multi value label category.
text Contents of the tag.
Response
{
    "type": "Security note",
    "text": "AV installed",
    "id": "12345"
}

Edit VM label

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

Delete VM label

Request

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

Response

Status.

VM notes 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 reference URI

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

VM notes resource model

The following fields are defined:

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

Operations on VM notes

Get VM notes

Request

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

Response

Representation of VM notes.

Add VM note

Request

POST https://cloud.skytap.com/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,
    "time": "2015/07/15 15:20:47 -0700",
    "text": "message"
}

Edit VM note

Request

PUT https://cloud.skytap.com/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/vms/{vm-id}/notes/{note-id}

Response

Status.

VM network adapters 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 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/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}

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

Network adapters resource model

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

Field Name Type Access Description
hostname string rw Limited to 32 characters. Valid characters are lowercase letters, numbers, and hyphens. Cannot begin or end with hyphens. Cannot be gw.
id string ro Identifier.
ip IP v4 address rw Internally, Skytap uses DHCP to provision an IP address (for example, 10.1.0.37) based on the MAC address. Skytap won’t assign the same IP address to multiple interfaces on the same network. This field can be modified if you want to provide your own network information.
Each segment of the IP address must be within the valid range (0 to 255, inclusive).
mac string rw for x86 VMs
ro for Power VMs		 Internally, Skytap provisions a MAC address for the network adapter (for example, 00:1e:c2:c3:52:61). Skytap won’t assign the same MAC address to multiple interfaces. This field can be modified if you want to provide your own network information.
  • MAC addresses must begin with the hexadecimal digits 00:50:56.
  • The maximum value for a MAC address is `00:50:56:3F:FF:FF`.
  • The valid MAC address range is `00:50:56:00:00:00` to `00:50:56:3F:FF:FF`.
nat_addresses object ro This object will appear only on networks that are connected to a NAT-enabled network via ICNR or a VPN tunnel. It contains two arrays:
  • The vpn_nat_addresses array will provide the NAT IP and details about the associated VPN. Includes: ip_address, vpn_id, vpn_name, and vpn_url.
  • The network_nat_addresses array will provide the NAT IP address and details about the connected network. Includes: ip_address, network_id, network_name, network_url, configuration_id, and configuration_url.
network_id integer rw ID of the network that this network adapter is attached to.
network_name string ro Name of the network that this network adapter is attached to.
network_subnet string ro Subnet of network that this network adapter is attached to.
network_type string ro Type of network that this network adapter is attached to.
network_url URI ro URL for the network that this network adapter is attached to.
nic_type string rw for x86 VMs
ro for Power VMs		 Network adapter type. One of: default, e1000, pcnet32, vmxnet, vmxnet3, or e1000e. UTF-8 character type.
Always default for Power VMs.

Not all NIC types are supported for all VMs; the VM guest operating system setting determines which NICs are supported.
promiscuous Boolean rw for x86 VMs
ro for Power VMs		 Indicates whether promiscuous mode is enabled.
By default, this is set to false. Always false for Power VMs.

This field will be visible if promiscuous mode permissions are enabled for the customer account; otherwise, this field is hidden. This field is also read-only, unless the user has permission to edit promiscuous mode settings. For more information, see Enabling Promiscuous Mode on a Network Adapter.
public_ips_count integer 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 array 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 isn't 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 don’t appear in this list.
services array ro An array of a published services attached to the VM. To add a published service, see Published Service Resource.
services_count integer ro Number of published services attached to the VM.
status string ro Runstate status of the VM that this network is attached to.
vm_id integer ro ID of the VM that this network is attached to.
vm_name string ro name of the VM that this network is attached to.

Supported operations on network adapters

Get network adapter

Request

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

GET https://cloud.skytap.com/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/configurations/{configuration-id}/vms/{vm-id}/interfaces.json

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

Response

Network interface elements

Create network adapter

Request

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

{
    "nic_type": "default"
}

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

Required parameters

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

This action isn’t supported for VMs in templates.

Response

New network adapter element

Update network adapter

Request

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

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

Required parameters

One or more of the following:

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

Notes

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

Updated network adapter

Connect network adapter to network

Request

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

{
    "network_id": "123456"
}

Required parameters

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

This action isn’t supported for VMs in templates.

Response

Connected network adapter

Add/remove published services

See Published Resource.

Add/remove secondary IPs

See Secondary IP Resource.

Add dynamic public IP with DNS name to a network adapter

Request

POST https://cloud.skytap.com/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/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/dynamic_public_ips/{public-ip-attachment-key}.json

{
    "hostname": "new-name"
}

Requirements:

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

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

[
    {
        "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/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/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/ips.json

{
    "ip": "10.0.0.1"
}

Required parameters

ip Static public IP address
Response

Static public IP attached to specified network

View static public IPs attached to a network adapter

Request

GET https://cloud.skytap.com/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/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/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/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}

Notes

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

Network adapter is deleted

Published services 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 reference URI

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

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

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

Published services resource model

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

Field Name Type Access Description
external_ip string ro Exposed routable host address. Connections to this address and port (below) are routed to the internal port in the guest VM. The external IP and port are selected by Skytap.

For the IP address that the returned URL resolves to, see: Published services.
external_port integer ro Exposed routable port. The port number is selected by Skytap.
id string ro Identifier.
internal_port integer rw The port that is exposed on the interface. Typically this will be dictated by standard usage (e.g., port 80 for http traffic, port 22 for SSH).

Operations on published services

Get published service description

Request

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

GET https://cloud.skytap.com/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/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/services.json

GET https://cloud.skytap.com/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/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/services.json

{
    "internal_port": 8080
}

Required parameters

internal_port Port number you want to open.

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

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

Response

Representation of new published service.

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

Delete a published service

Request

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

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

Response

Status

Secondary IP addresses resource

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

Secondary IP addresses reference URI

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

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

Secondary IP addresses resource model

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

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

Operations on secondary IP addresses

List secondary IP addresses

Request

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

Response

Representation of the secondary IP addresses

Add a secondary IP address

Request

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

{
    "address": "10.0.2.2"
}

Required parameters

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

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

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

Edit a secondary IP address

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

Detach a secondary IP address

Request

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

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

Response

Removed secondary IP address.

VM metadata resource

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

VM metadata reference URI

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

VM metadata resource model

The following fields are defined:

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

Supported operations on VM metadata

Get VM metadata

Request

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

Response

Contents of metadata field.

Update VM metadata

Request

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

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

Required parameters

contents Any text you want saved in the user_data field.

This action isn’t supported for VMs in templates.

Response

Updated metadata field.

Remove contents of VM metadata field

Request

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

{
    "contents": null
}

This action isn’t supported for VMs in templates.

Response

Updated metadata field.

Environment Muti-Attach Storage resource

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

Notes

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

    To increase the total number of disks that can be connected to the Power VMs in an environment, contact Skytap Support

Environment multi-attach storage reference URI

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

Environment multi-attach storage resource model

The element name is multi_attach_storage_groups.

The following fields are defined:

Field Name Type Access Description
id string ro ID of the group.
configuration_id string ro ID of the environments used to create the group .
hypervisor string rw The group hypervisor type. Currently, the only valid value is power.
name string rw The name of the group.
vm_attachments array rw Array of VMs attached to the group value.
storage_allocations array rw Array of storage allocations that are part of the group.
NameTypeAcccessDescription
idrostringUnique ID of this storage allocation
depot_keyrostringID of the storage depot
depot_typerostringStorage depot type
sizerostringThe size of the storage allocation in MB
disk_attachmentsrostringArray of storage devices (disks) configured for this allocation
NameTypeAcccessDescription
idrostringUnique ID of the associated storage allocation
controllerrostringID of the disk controller
bus_typerostringThe storage controller bus type. Always scsi
bus_idrostringThe ID of the storage controller bus
lunrostringThe LUN (Logical Unit Number) of the storage device

Operations on multi-attach storage groups

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

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

Get a multi-attach storage single group for an environment

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

Multi-Attach Storage disk set

Sample response

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

Get multiple multi-attach storage groups for an environment

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

Representation of all multi-attach storage groups in the environment

Sample response

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

Create a multi-attach storage group

Request
POST https://cloud.skytap.com/configurations/{configuration-id}/multi_attach_storage_groups.json
[
    {
    "name":"TestGroup",
    "hypervisor": "power"
    }
]

Required parameters

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

Sample response

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

Delete a multi-attach storage group

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

Request
DELETE https://cloud.skytap.com/multi_attach_storage_groups/{storage-group-id}
Response

Status.

Create storage within a multi-attach storage group

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

Request
POST https://cloud.skytap.com/multi_attach_storage_groups/{storage-group-id}/storage_allocations.json
{
    "spec":
    {
        "volume":
        [
            2048,
            2048
        ]
    }
}

Required parameters

Required Parameters
volume The disk size in MB.
Response

Updated representation of the multi-attach storage groups.

Sample response

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

Delete storage from within a multi-attach storage group

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

Request
DELETE https://cloud.skytap.com/multi_attach_storage_groups/{storage-group-id}/storage_allocations.json
{
    "allocation_ids": 
    [
        "storage-allocation-id-30", 
        "storage-allocation-id-31"
    ]
}
Response

Updated representation of the multi-attach storage groups.

Attach a multi-attach storage group to a VM

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

Request
POST https://cloud.skytap.com/multi_attach_storage_groups/{storage-group-id}/vm_attachments.json
{
    "vm_ids": 
    [
        "12345678",
        "87654321"
    ]
}
Response

Updated representation of the multi-attach storage groups.

Sample response

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

Detach a multi-attach storage group from a VM

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

Request
DELETE https://cloud.skytap.com/multi_attach_storage_groups/{storage-group-id}/vm_attachments.json
{
    "vm_ids": 
    [
        "12345",
        "23456"
    ]
}
Response

Updated representation of the multi-attach storage groups.

Sample response

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

Environment networks resource

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

Environment networks reference URI

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

Environment networks resource model

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

Field Name Type Access Description
domain string rw Domain name for the Skytap network. Limited to 64 characters.
Valid characters are lowercase letters, numbers, and hyphens. Can’t be blank, must not begin or end with a period, and must start and end with a letter or number.
This field can be changed only when all virtual machines in the environment are stopped (not suspended or running).

domain can only be defined and edited for automatic networks (see network_type below).
gateway string rw Gateway IP address.
id integer ro Identifier.
name string rw User defined name of the network. Limited to 255 characters. UTF-8 character type.
nat_pool_remaining integer ro Remaining assignable IP addresses for NAT. Does not appear if network isn’t NAT-enabled.
nat_pool_size integer ro The total number of IP addresses for external mapping. Does not appear if network isn’t NAT-enabled.
nat_subnet string rw A CIDR block which determines the external IP addresses which will be assigned to network interfaces on connected networks. The larger the subnet, the larger the IP pool will be. Does not appear on manual networks or if an automatic network isn’t NAT-enabled.
Cannot overlap with subnet (see above).
Can be unset with "".
network_type string rw Type of network (must be automatic or manual).
Once it’s defined, this field can’t be edited.
primary_nameserver string rw User-provided primary name server for this network.
On an automatic network, Skytap provisions the domain name servers. Users can optionally override this and provide their own primary and secondary name servers. If this value is set, all name resolution requests are routed to this server.
Must be a valid IPv4 address.
region string ro Region that the resource is housed in (for example, US-West).
secondary_nameserver string rw User-provided secondary name server for this network.
The secondary_nameserver is used if the primary_nameserver doesn’t resolve.
subnet string rw Defines the subnet address and subnet mask size in CIDR format (for example, 10.0.0.0/24). IP addresses for the VMs are assigned from this subnet and standard network services (DNS resolution, CIFS share, routes to Internet) are defined appropriately for it.
The subnet mask size must be between 16 and 30. Valid characters are lowercase letters, numbers, and hyphens. Cannot be blank, must not begin or end with a period, and must start and end with a letter or number.

This field can be changed only when all virtual machines in the environment are stopped (not suspended or running).
The subnet field replaces the previous subnet_addr and subnet_size fields. The subnet_addr and subnet_size fields are still supported, if you would like to define the subnet address and subnet size separately.
tunnelable Boolean rw If true, this network can be connected to other networks.
tunnels array ro List of connections between this network and other networks.
vpn_attachments array ro Representations of the relationships between this network and any VPN or Private Network Connections it’s attached to, including whether the network is currently connected.

Operations on environment networks

Get network description

Request

GET https://cloud.skytap.com/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/configurations/{configuration-id}/networks.json

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

Required and optional parameters

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

Representation of the new network

{
    "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/configurations/{configuration-id}/networks.json

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

Required and optional parameters

Required Parameters
name Network name
network_type manual
subnet Subnet address and subnet mask size
gateway Network gateway
Optional Parameters
primary_nameserver Primary custom DNS server
secondary_nameserver Secondary custom DNS server; can only be specified if a primary name server is specified; must be combined with primary_nameserver
tunnelable If true, network can be connected to other networks
Response

Representation of the new network

{
    "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/configurations/{configuration-id}/networks/{network-id}.json

{
    "name": "New network name"
}

Required parameters

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/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/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/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/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/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/configurations/{configuration-id}/networks/{network-id}

Response

Network element is deleted.

Environment notes resource

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

Environment notes reference URI

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

Environment notes resource model

The following fields are defined:

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

Operations on environment notes

Get environment notes

Request

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

Response

Sample response body:

[
    {
        "id": "1234",
        "user_id": 9999,
        "time": "2015/09/08 00:26:48 -0800",
        "text": "Defect found"
    },
    {
        "id": "1235",
        "user_id": 8888,
        "time": "2015/09/09 00:23:12 -0800",
        "text": "See JIRA-1234"
    }
]

Add environment note

Request

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

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

Required parameters

text Any text you want saved as a note.
Response

New note.

Edit environment note

Request

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

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

Required parameters

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

Updated note.

Delete environment note

Request

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

Response

Status.

Environment metadata resource

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

Environment metadata reference URI

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

Environment metadata resource model

The following fields are defined:

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

Operations on environment metadata

Get environment metadata

Request

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

Response

Representation of the user_data field.

Update environment metadata

Request

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

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

Parameters

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

Updated representation of the user_data field.

Remove environment metadata

Request

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

{
    "contents": null
}
Response

Updated representation of the user_data field.

Environment sharing portals resource

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

Environment sharing portals reference URI

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

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

Environment sharing portals resource model

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

Field Name Type Access Description
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).

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

This field is required if custom_content_enabled is true.
custom_content_enabled Boolean rw If true, the sharing portal includes a tab with the contents of the custom_content field. The tab must have a name, defined in the custom_title field below.
custom_content_is_default Boolean rw If true, the custom content tab opens first in the sharing portal.
custom_title string rw Name of the custom content tab. Max. 32 characters.

This field is required if custom_content_enabled is true.
desktops_url string ro Access URL for single_url sharing portals. For multiple_url sharing portals, the access URLs are listed as desktop_url in the VMs array (see below).
end_time string 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.
expiration_date string rw (Optional) The date and time the sharing portal expires. After this time, no VM can be accessed via the sharing portal. Use the format: yyyy/mm/dd hh:mm:ss (“2015/11/28 10:45:00”)

expiration_date and expiration_date_tz must be entered as a pair.
expiration_date_tz string rw (Optional) Time zone for the expiration date. For a list of time zones, see Time Zones and UTC Offsets.

expiration_date and expiration_date_tz must be entered as a pair.
id integer ro Unique ID for the sharing portal.
multiple_url Boolean ro Indicates whether the publish_set_type is multiple_url.
name string rw Descriptive name of sharing portal; doesn’t need to be unique.
password string wo If a password is included in this field, it’s required to access the sharing portal. If you don’t want to require a password for access, enter an empty string in this field.

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

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

If ********** is sent as the value of the password element, it's ignored and the current password isn't changed.
publish_set_type string rw Type of sharing portal.
single_urlSingle sharing portal
multiple_urlSharing portal set
runtime_left_in_seconds integer ro For single_url sharing portals with a runtime_limit set, this field display the remaining time that the sharing portal is available. For all other conditions, this field is null.
runtime_limit integer rw (Optional) The number of minutes the VMs can be accessed via a sharing portal. Once this limit is met, the VMs will be set to “do_not_publish”; they won’t be suspended by this action. You can increase the limit to provide additional access. null if not in use.
sso_required Boolean rw This field is visible only for accounts with SSO enabled.
If true, SSO is used to authenticate users accessing the sharing portal. If true, password (above) must be empty.
start_time string 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.
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 is used (http://help.skytap.com/#help-with-vms.html).
String format must be one of the following:
  • http://example.com
  • https://example.com
  • mailto:support@example.com
time_zone string rw (Optional) Defines the time_zone for the access window. If this isn’t defined, your personal time zone is used. For a list of time zones, see Time Zones and UTC Offsets.
url string ro URL of the sharing portal resource for UI and API access.
vms array ro/rw Representation of VMs in the sharing portal.
Field NameTypeAccessDescription
accessstringrwVM access level. Must be one of:
  • do_not_publish (Labeled "Excluded" in the UI).
  • run_and_use (Labeled "Full Control" in the UI).
  • use
  • view_only

For access level descriptions, see Sharing VMs and environments with sharing portals.

desktop_urlstringroAccess URL for the VM.
errorBooleanroIndicates whether the VM has an error.
error_detailsobectroProvides details about any errors with the environment.
namestringroVM name
run_and_use.Booleanrotrue if the access level is run_and_use.
vm_refURIrwVM URI

Operations on environment sharing portals

List sharing portals

Request

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

Response

Representation of sharing portals.

Create sharing portal

Request

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

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

Required and optional parameters

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
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/configurations/111111/publish_sets/22222",
    "publish_set_type": "multiple_url",
    "runtime_limit": null,
    "runtime_left_in_seconds": null,
    "expiration_date": null,
    "expiration_date_tz": null,
    "start_time": null,
    "end_time": null,
    "time_zone": null,
    "multiple_url": true,
    "password": null,
    "use_smart_client": true,
    "sso_required": false,
    "vms": [
        {
        "name": "Ubuntu Linux (64-bit)",
        "access": "use",
        "run_and_use": false,
        "vm_ref": "https://cloud.skytap.com/vms/12345",
        "error": false,
        "desktop_url": "https://cloud.skytap.com/vms/b62c0972cd373c801abcdefc316b54b8/desktops"
        },
        {
        "name": "Ubuntu Server",
        "access": "use",
        "run_and_use": false,
        "vm_ref": "https://cloud.skytap.com/vms/12345",
        "error": false,
        "desktop_url": "https://cloud.skytap.com/vms/b62c0972cd373c801abcdefc316b54b8/desktops"
        }
    ],
    "custom_content_enabled": false
}

{
    "id": "22222",
    "name": "default",
    "url": "https://cloud.skytap.com/configurations/111111/publish_sets/22222",
    "publish_set_type": "multiple_url",
    "runtime_limit": 120,
    "runtime_left_in_seconds": null,
    "expiration_date": "2015/05/20 19:00:00",
    "expiration_date_tz": "Pacific Time (US & Canada)",
    "start_time": "08:00",
    "end_time": "17:00",
    "time_zone": "Pacific Time (US & Canada)",
    "multiple_url": true,
    "password": "**********",
    "use_smart_client": true,
    "sso_required": false,
    "vms": [
        {
        "name": "Something else",
        "access": "use",
        "run_and_use": false,
        "vm_ref": "https://cloud.skytap.com/vms/12345",
        "error": false,
        "desktop_url": "https://cloud.skytap.com/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/configurations/{configuration-id}/publish_sets/{publish-set-id}.json

Response

The reference model in the body of the response.

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

View desktop URL

Request

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

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

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

Response

A representation of the desktop URL.

Edit sharing portal

Request

PUT https://cloud.skytap.com/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/configurations/{configuration-id}/publish_sets/{publish-set-id}

Response

Status code

Environment VM sequencing stages resource

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

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

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

Environment VM sequencing stages reference URI

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

Environment VM sequencing stages resource model

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

Field Name Type Access Description
delay_after_finish_seconds integer rw The number of seconds to wait after completing this stage before starting the next stage; this can be between 0 and 3600 (e.g., 60 minutes).

This field is only recognized for start up sequences. Delays are ignored during suspend or shut down sequences.
index integer ro The index of this stage relative to the other stages in the environment; 0 indicates the first stage, 1 indicates the second stage, n indicates stage (n + 1).
vm_ids array (string) rw The IDs of the VM instances in a stage.

Operations on Environment VM sequencing stages

Get the VM sequence description

Request

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

Response

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

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

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

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

Edit the whole VM sequence

Request

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

An example is provided below:

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

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

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

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

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

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

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

View a stage within the VM sequence

Request

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

Response

Returns the specified stage in the following format:

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

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

Edit a stage within the VM sequence

Request

PUT https://cloud.skytap.com/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/configurations/{configuration-id}/staged_execution.json

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

Response

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

Field Name Type Description
action_type string The current action (run, suspend, shutdown, or poweroff).
current_stage_delay_after_finish_seconds integer The number of seconds to wait after completing this stage before starting the next stage; this can be between 0 and 3600 (e.g., 60 minutes).

This field is recognized only for start up sequences. Delays are ignored during suspend, shut down, or power off sequences.
current_stage_index integer The index of this stage relative to the other stages in the configuration; 0 indicates the first stage, 1 indicates the second stage, n indicates stage (n + 1).
current_stage_finished_at timestamp Time that the current stage finished executing.
vm_ids array (string) The IDs of the VM instances whose run states are changing.

Example response body:

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

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

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

Cancel a running VM sequence

Request

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

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

Response

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

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

Templates resource

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

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

Templates reference URI

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

Templates resource model

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

Field Name Type Access Description
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.
container_hosts_count integer ro Number of container host VMs in the template
containers_count integer ro Number of containers in the template
description string rw User-defined description. Limited to 1000 characters. Null allowed. UTF-8character type.
id string ro Template identifier
name string rw User-defined name. Limited to 255 UTF-8 characters. Defaults to source environment’s name with - Copy added if null is provided.
networks array ro Array of networks in the template
public Boolean ro Indicates whether the template is from the Skytap public library.
publish_sets array ro Array of sharing portals in the template.
region string ro Region that the resource is housed in (for example, US-West)
region_backend string ro Region that the resource is housed in (for example, US-West)
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 doesn't appear in the normal representation of a template; it must be called directly via a GET request to
https://cloud.skytap.com/templates/<template-id>/user_data.
vms array ro Array of virtual machines in the template
url URI ro URI reference for template

Templates 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/templates/{template-id}.json

Response

Representation of the template resource.

Get list of templates

Request

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

Scope, filter, sort, and paginate parameters

An optional filter parameter can be used to filter the list of templates.

Notes

  • The filter parameter will search for matches on the template name, template description, template tags, template labels, VM names within the template, and VM labels within the template.
  • For partial word matches, include a `*` wildcard at the end of the word. `*` isn't supported at the beginning or middle of a word.
  • When multiple search terms are used, only records which match all of the terms are returned (boolean AND). Multiple search terms don't have to be in any particular order.
  • The separators between words (delimiters) can be spaces (represented in the URL as either + or %20) or commas.

For example, to see a list of templates that contain “Puppet”:

GET https://cloud.skytap.com/templates?filter=Puppet

Response

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

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

Create template

Templates are created by saving an environment as a template.

Request

POST https://cloud.skytap.com/templates.json

{
    "configuration_id": "123456"
}

Parameters

Required parameters
configuration_id ID of the environment you want to create a template from
Optional Parameters
publish_sets Indicates whether to include the environment sharing portals in the template. Either true or false. By default, the sharing portals aren’t saved.
vm_instance_multiselect Array of one or more VM IDs to include in the template. If this parameter isn’t included, all VMs in the environment are saved in the template.
network_multiselect Array of one or more network IDs to include in the template. If this parameter isn’t included, all networks in the environment are saved in the template.
live_copy Save running VMs without suspending them. We recommend that you quiesce VM activity on running VMs before you copy them. Either true or false.
mas_group_multiselect Array of one or more multi-attach storage groups to include in the template. If this parameter isn’t included, all multi-attach storage groups in the environment are saved in the template. 
{
    "configuration_id": "123456",
    "publish_sets": true,
    "vm_instance_multiselect": [
        "12345"
    ],
    "network_multiselect": [
        "11111"
    ],
    "mas_group_multiselect": [
        "mas-2dF0vXLdtYetYxxjnEygx6vwKlM",
        "mas-2dF0vXLdtYetYxxjnEyawdcmklp"
    ]
}
Response

If successful, returns a representation of the new template.

Returns a 409 error if the environment has a running Power VM; these can’t be suspended. Shut down the VM and retry.

Edit template

Request

PUT https://cloud.skytap.com/templates/{template-id}?{attr-name}={attr-value}

Response

Representation of the updated template.

Change template owner

Request

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

{
    "owner": "12345"
}

Parameters

Required parameters
owner ID of the user you want to be the new template owner. If the user is a restricted user, you must also include reassign_context with the ID of a project that the user has editor or manager privileges in.
Optional Parameters
reassign_context Contains a project ID; used to add the template 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 template. The operation fails if the new owner doesn’t have enough remaining space in their storage limit for the template.

Copy template

Request

POST https://cloud.skytap.com/templates.json

{
    "template_id": "12345"
}

Required parameters

template_id ID of the template you want to copy
Response

New copy of specified template

Copy template to a different region

Request

POST https://cloud.skytap.com/templates.json

{
    "template_id": "12345",
    "target_region": "US-West",
    "resource_mapping": {
        "public_ip": {
            "1.2.3.0": "4.5.6.0"
            },
        "vpn": {
            "vpn-12345": "vpn-67890"
        }
    }
}

The VMs in the template must be in a powered-off state.

It is possible to forcefully power off the VMs prior to the copy operation: however, this may cause system instability in the resulting copy. If you still want to conduct the copy, you can add an optional flag. This flag is copy_to_region_vm_status_override and the value should be set to “true”.

Parameters

Required parameters
template_id ID of the template you want to copy
target_region Region where you want the new template to be hosted. (APAC-2, AU-Sydney-I-1, CAN-Toronto, CN-HongKong-M-1, DE-Frankfurt-1-1, EMEA, IE-Dublin-M-1, IN-Pune-M-1, NL-Amsterdam-M-1, SG-Singapore-M-1, UK-Londond-M-1, US-Central, US-East-2, US-Texas-M-1, US-Virginia-M-1, or US-West)
Optional parameters
resource_mapping Object that maps VPNs and public IPs in the current region to VPNs and public IPs in the target region.
Response

New copy of specified template in the target region (in this example, US-West).

If any VMs are suspended, the copy operation will automatically fail.

Generate Vagrantfile

Request

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

Optional URL parameters

To customize the Vagrantfile creation, include one or both of the following URL parameters:

include_api_credentials=true The Vagrantfile will contain your account user name and API token.
By default, the Vagrantfile contains <your username> and <your api token> placeholder values.
This parameter will be ignored if you don’t have API tokens enabled in your account.
include_hardware_properties=true The Vagrantfile will include the VMs’ CPU, RAM, and guest OS properties.
By default, these properties are omitted.

The Vagrantfile is retrieved with a standard HTTP request. The response is UTF-8 text.

Response
# This Vagrantfile was generated from the "SharePoint Farm"
# template: https://cloud.skytap.com/templates/1234567

Vagrant.configure(2) do |config|
    # The "skytap/empty" box contains minimal metadata. The source VMs
    # are specified below using the vm_url setting.
    config.vm.box = "skytap/empty"

    # Credentials for the Skytap REST API. If you plan to check this
    # Vagrantfile into source control, consider omitting this block,
    # and setting the environment variables VAGRANT_SKYTAP_USERNAME
    # and VAGRANT_SKYTAP_API_TOKEN instead.
    config.vm.provider :skytap do |skytap|
        skytap.username  = "<your username>"
        skytap.api_token = "<your api token>"
    end

    config.vm.define :vm1 do |vm1|
        vm1.vm.provider :skytap do |skytap|
            # VM name: Active Directory Server
            skytap.vm_url = "https://cloud.skytap.com/vms/111111"
        end
    end

    config.vm.define :vm2 do |vm2|
        vm2.vm.provider :skytap do |skytap|
            # VM name: SharePoint Web Tier
            skytap.vm_url = "https://cloud.skytap.com/vms/222222"
        end
    end

end

Delete template

Request

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

Deleted templates can’t be recovered.

Response

Status only

Delete templates

Request

DELETE https://cloud.skytap.com/templates/destroy_multiple.json

{
    "multiselect": [
        "123456",
        "123457",
        "123458",
        "123459"
    ]
}

Parameters

multiselect Array of the templates IDs for the templates that you want to delete.

Deleted templates can’t be recovered.

Response

Status only

Export templates report (.CSV)

Step 1: Create the report

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

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

Initial response

Sample response body:

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

    {
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/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/templates/exports/123456.csv

Response

Templates CSV report.

Template VMs resource

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

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

Template VMs reference URI

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

You can optionally specify the containing template in the URL, but this isn’t required (https://cloud.skytap.com/templates/<template-id>/vms/<vm-id>).

Template VMs 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 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/vms/{vm-id}.json

Response

Representation of selected virtual machine element.

Template networks resource

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

Template networks reference URI

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

Template networks resource model

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

Operations on template networks

Get template network

Request

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

Response

Representation of the network

Template labels resource

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

Template labels reference URI

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

Template labels resource model

Field Name Type Access Description
id integer ro Template label identifier.
tag_type string wo Each label must have a tag_type on PUT. This will be returned as type on GET.
One of: BugTag, PurposeTag, RegionNameTag, SecurityTag.
type string ro Read-only representation of the tag_type. One of: Bug ID (BugTag) , Category (PurposeTag), Region (RegionNameTag), Security note (SecurityTag).
text string rw Contents of the label. Max 255 characters.

Operations on template labels

Get template labels

Request

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

Response

Representation of the template labels

Add template label

Request

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

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

Required parameters

tag_type One of several options listed in the resource table above. The tag_type from the request is converted to type in the API response.
text Contents of the tag.
Response

Representation of the new template label

{
    "type": "Security",
    "text": "AV installed",
    "id": "1066"
}

Edit template label

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

Remove template label

Request

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

Response

Updated representation of the labels sub-resource.

Template sharing portals 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 reference URI

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

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

Template publish sets 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 template sharing portals

Get sharing portal

Request

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

Response

The reference model in the body of the response.

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

List template sharing portals

Request

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

Response

Representation of sharing portals.

Template VM sequencing stages resource

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

Template VM sequencing stages reference URI

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

Template VM sequencing stages 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 template VM sequencing stages

Get the VM sequence description

Request

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

Response

A list of the VM sequencing stages.

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

GET https://cloud.skytap.com/templates/<templates-id>/stages/excluded_vms.json

View a stage within the VM sequence

Request

GET https://cloud.skytap.com/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 limits resource

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

Notes

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

Account limits reference URI

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

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

Account limits 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, concurrent_storage_size, cumulative_svms, concurrent_public_ips, or concurrent_networks.
limit integer (various, see description) Current resource limit for the account.
Field NameTypeAccessDescription
concurrent_svmsintegerrwThe maximum amount of Metered RAM that may be used at the same time; applies to Metered RAM consumed by x86 VMs.
concurrent_svms_powerintegerrwThe maximum amount of Metered RAM that may be used at the same time; applies to Metered RAM units consumed by Power VMs.

Available only if your account is enabled for Power VMs.

concurrent_vmsintegerrwNumber of VMs that can be used at the same time.
concurrent_storage_sizeintegerrwMaximum storage limit for the account, units specified in MB.
cumulative_svmsintegerrwMaximum number of hours of cumulative Metered RAM usage for x86 VMs.
cumulative_svms_powerintegerroMaximum number of hours of cumulative Metered RAM usage for Power VMs.Returned only if your account is enabled for Power VMs.
concurrent_public_ipsintegerroMaximum number of public IP addresses.
concurrent_networksintegerroMaximum number of networks.
max_limit integer ro Max settable limit for the account; this is highest value that can be set for the quota. If max_limit is null, then the max limit is equal to the current limit.
quota_type string ro The type of resource the quota is measuring. One of concurrent_svms, concurrent_vms, concurrent_storage_size, cumulative_svms, concurrent_public_ips, or concurrent_networks.
region string ro The name of the region that the limit applies to. If limit applies to the whole account, this parameter contains global.
subscription integer ro The amount of resources you have budgeted for monthly usage; if you set the limit above the reserved capacity, you can allow additional usage at an additional cost.
units string ro Specifies the unit of measure (for example, MB or integer).
usage integer ro The amount of resource in use or consumed (depending on the resource).

Operations on account limits

List all customer limits

Request

GET https://cloud.skytap.com/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",
    "quota_type": "concurrent_vms",
    "units": "integer",
    "limit": 10,
    "region": "global",
    "usage": 5,
    "subscription": 10,
    "max_limit": 10
  },
  {
    "id": "concurrent_svms",
    "quota_type": "concurrent_svms",
    "units": "integer",
    "limit": 20,
    "region": "global",
    "usage": 10,
    "subscription": 20,
    "max_limit": 20
  },
  {
    "id": "cumulative_svms",
    "quota_type": "cumulative_svms",
    "units": "hours",
    "limit": 100,
    "region": "global",
    "usage": 0,
    "subscription": 100,
    "max_limit": 100
  },
  {
    "id": "concurrent_storage_size",
    "quota_type": "concurrent_storage_size",
    "units": "MB",
    "limit": 102400,
    "region": "global",
    "usage": 20480,
    "subscription": 102400,
    "max_limit": 102400
  },
  {
    "id": "concurrent_networks",
    "quota_type": "concurrent_networks",
    "units": "integer",
    "limit": 20,
    "region": "global",
    "usage": 4
  },
  {
    "id": "concurrent_public_ips",
    "quota_type": "concurrent_public_ips",
    "units": "integer",
    "limit": 6,
    "region": "global",
    "usage": 2
  }
]

{
  "global": [
    {
      "id": "concurrent_vms",
      "quota_type": "concurrent_vms",
      "units": "integer",
      "limit": 10,
      "region": "global",
      "usage": 5,
      "subscription": 10,
      "max_limit": 10
    },
    {
      "id": "cumulative_svms",
      "quota_type": "cumulative_svms",
      "units": "hours",
      "limit": 100,
      "region": "global",
      "usage": 50,
      "subscription": 100,
      "max_limit": 100
    }
  ],
  "US-West": [
    {
      "id": "concurrent_svms",
      "quota_type": "concurrent_svms",
      "units": "integer",
      "limit": 10,
      "region": "US-West",
      "usage": 0,
      "subscription": 10,
      "max_limit": 10
    },
    {
      "id": "concurrent_storage_size",
      "quota_type": "concurrent_storage_size",
      "units": "MB",
      "limit": 51200,
      "region": "US-West",
      "usage": 10240,
      "subscription": 51200,
      "max_limit": 51200
    },
    {
      "id": "concurrent_networks",
      "quota_type": "concurrent_networks",
      "units": "integer",
      "limit": 10,
      "region": "US-West",
      "usage": 2
    },
    {
      "id": "concurrent_public_ips",
      "quota_type": "concurrent_public_ips",
      "units": "integer",
      "limit": 3,
      "region": "US-West",
      "usage": 1
    }
  ],
  "US-East-2": [
    {
      "id": "concurrent_svms",
      "quota_type": "concurrent_svms",
      "units": "integer",
      "limit": 10,
      "region": "US-East-2",
      "usage": 0,
      "subscription": 10,
      "max_limit": 10
    },
    {
      "id": "concurrent_storage_size",
      "quota_type": "concurrent_storage_size",
      "units": "MB",
      "limit": 51200,
      "region": "US-East-2",
      "usage": 10240,
      "subscription": 51200,
      "max_limit": 51200
    },
    {
      "id": "concurrent_networks",
      "quota_type": "concurrent_networks",
      "units": "integer",
      "limit": 10,
      "region": "US-East-2",
      "usage": 2
    },
    {
      "id": "concurrent_public_ips",
      "quota_type": "concurrent_public_ips",
      "units": "integer",
      "limit": 3,
      "region": "US-East-2",
      "usage": 1
    }
  ]
}

View customer limits in a region

Request

GET https://cloud.skytap.com/company/quotas.json?region=US-West

Response

Representation of the region’s limits.

[
  {
    "id": "concurrent_svms",
    "quota_type": "concurrent_svms",
    "units": "integer",
    "limit": 10,
    "region": "US-West",
    "usage": 0,
    "subscription": 10,
    "max_limit": 10
  },
  {
    "id": "concurrent_storage_size",
    "quota_type": "concurrent_storage_size",
    "units": "MB",
    "limt": 51200,
    "region": "US-West",
    "usage": 10240,
    "subscription": 51200,
    "max_limit": 51200
  },
  {
    "id": "concurrent_networks",
    "quota_type": "concurrent_networks",
    "units": "integer",
    "limit": 10,
    "region": "US-West",
    "usage": 2
  },
  {
    "id": "concurrent_public_ips",
    "quota_type": "concurrent_public_ips",
    "units": "integer",
    "limit": 3,
    "region": "US-West",
    "usage": 1
  }
]

Edit a customer limit

Request

Select customer limits can be edited through the API. Each list modification must be a separate request.

If you would like to edit a limit that is read only or where the max settable limit is null, contact your Skytap representative.

PUT https://cloud.skytap.com/company/quotas/{quota_type}.json

{
  "limit": 150
}

Required parameters

Required parameters
limit The new limit (integer).
region If you’re editing a regional limit, you must include a region parameter. If you’re editing a global limit, no region is required.
Response

The updated limit.

Assets resource

Files uploaded to your account are called assets. Assets can be downloaded onto VMs, as well as shared with other users via projects.

Assets can’t be created or modified. You can view assets and reference them.

Assets reference URI

https://cloud.skytap.com/assets/{asset-id}

Assets 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.
owner URI ro User-ref for the asset’s owner. This field doesn’t exist for Skytap-owned public assets.
public Boolean ro Indicates whether the asset is in the Skytap public library.
region string ro Region where the asset is housed (for example, us-west).
size integer ro Size (in bytes).
url URI ro URI reference for the asset.

Operations on assets

Get asset description

Request

GET https://cloud.skytap.com/assets/{asset-id}

Response

An asset element.

List assets

Request

GET https://cloud.skytap.com/assets

Filter parameters

An optional filter parameter can be used to filter the list of assets.

Notes:

  • The filter parameter will search for matches on the asset name.
  • For partial word matches, include a * wildcard at the end of the word. * isn’t supported at the beginning or middle of a word.
  • When multiple search terms are used, only records which match all of the terms are returned (boolean AND). Multiple search terms don’t have to be in any particular order.

The separators between words (delimiters) can be spaces (represented in the URL as either + or %20) or commas.

For example, to see a list of assets that contain “Skytap Helper”:

GET https://cloud.skytap.com/assets?filter=Skytap+Helper

Response

Returns a list of assets. Data within the assets isn’t returned.

Export an assets report (.CSV)

Request
Step 1: Create the report

POST https://cloud.skytap.com/assets/exports

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

Response
Initial response

Sample response body:

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

    {
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/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/assets/exports/123456.csv

Response

The report is downloaded.

Auditing reports resource

The auditing report resource can be used to create a .CSV report of account activity that occurred during a specified span of time.

Notes

  • You must be a Skytap administrator to request auditing reports.
  • You can view up to two years of audit data.

Report request limits

Skytap limits the number of concurrent report requests:

  • 1,000 per account
  • 100 per user

Most requests (Skytap UI or API) persist for 15 minutes. Reports requested via “Email CSV” persist for one week.

The report response is limited to 5,000 report entries. For reports larger than 100 5,000 report entries, use CSV export to download results.

Auditing reports reference URI

https://cloud.skytap.com/auditing/exports

Auditing reports resource model

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

Field Name Type Access Description
id string ro ID of the auditing report.
ready Boolean ro Specifies whether the report is ready to download.
url string ro URL where the report can be downloaded.

Optional report parameters

The following fields can also be defined to specify the report parameters.

Field Name

Type

Access

Description

activity

string

rw

Activity name (see table of Auditing Report Activity Names below)
If an activity name isn’t defined, the report will include all activities.

user

integer

rw

User ID number
If a user ID isn’t defined, the report will include all users.

department

integer

rw

Department ID number
If a department ID isn’t defined, the report will include activity by all departments.

project

integer

rw

Project ID number
If a project ID isn’t defined, the report will include all activity in all projects.

region

string

rw

Region name
If a region name isn’t defined, the report will include activity in all regions.

date_start

object

rw

Report start date

The report start date contains five values (year, month, day, hour, and minute).

The JSON representation is:

{
    "date_start":  {
        "year": 2017,
        "month": 1,
        "day": 1,
        "hour": 0,
        "minute": 0
    }
}

Valid entries:

year 2010 to current year
month 1 to 12
day 1 to 31
hour 00 to 23
minute 00 to 59

If a start date isn’t defined, the start date will be set to yesterday (at the current time).

If a start date is defined, it must come before the end date (see below).

date_end

object

rw

Report end date

The report end date contains five values (year, month, day, hour, and minute).

The JSON representation is:

{
    "date_end":  {
        "year": 2017,
        "month": 2,
        "day": 1,
        "hour": 0,
        "minute": 0
    }
}

Valid entries:

year 2010 to current year
month 1 to 12
day 1 to 31
hour 00 to 23
minute 00 to 59

If an end date isn’t defined, the end date will be set to the current date and time.

environment_id

string

rw

If an environment or template ID isn’t defined, the report will include activity in all environments and templates.

notify_by_email

Boolean

rw

Whether you want the report emailed to you when it’s complete.

email

string

ro

Email address the report will be sent to; this is the email address of the API user.

Auditing report activity names

Activity names that can be used to filter the auditing report.

Activity Name Activity Description
AddLabelHistory Add Label
AddPublicIpAddressHistory Add Public Ip Address
AddSecondaryIpAddress Add Secondary Ip
AddTagHistory Add Tag
ShareHistory Add To Project
AddUserToDepartmentHistory Add User To Department
AddUserToGroupHistory Add User To Group
SsoAnonymousLoginHistory Anonymous Single Sign On Login
ApiTokenResetHistory Api Token Reset
AttachPublicIpAddressToVmInterfaceHistory Attach Public Ip Address To Vm Interface
AttachDynamicPublicIpToVmInterfaceHistory Attach Dynamic Public Ip to VM Interface
AttachVpnHistory Attach Vpn
BrowserActivationHistory Browser Activation
CancelExecutionSequenceHistory Cancel Vm Sequence Execution
ReassignAllResourcesHistory Change Owner Of All Resources
ReassignResourceHistory Change Resource Owner
CommissionContainerHostHistory Commission Container Host
ConnectVpnHistory Connect Vpn
ControlContainerHistory Control Container
CloneConfigurationHistory Copy Environment
CopyConfigurationStartHistory Copy Environment to Region
CloneTemplateHistory Copy Template
CopyTemplateStartHistory Copy Template to Region
CreateContainerHistory Create Container
CreateContainerRegistryHistory Create Container Registry
CreateCsvExportHistory Create Csv Export
CreateDepartmentHistory Create Department
CreateConfigurationHistory Create Environment
CreateExportJobHistory Create Export Job
CreateGroupHistory Create Group
CreateImportJobHistory Create Import Job
CreateIpRangeHistory Create Ip Range
CreateLabelCategoryHistory Create Label Category
CreateNetworkHistory Create Network
CreateNetworkAdapterHistory Create Network Adapter
CreateNotificationRuleHistory Create Notification Rule
CreateProjectHistory Create Project
CreatePublishedServiceHistory Create Published Service
CreateRoleHistory Create Role
CreateScheduleHistory Create Schedule
PublishConfigurationHistory Create Template From Environment
CreateTunnelHistory Create Tunnel
CreateUserHistory Create User
CreateVpnHistory Create Vpn
CsvExportEmailHistory Csv Export Email
DeactivateUserHistory Deactivate User
DecommissionContainerHostHistory Decommission Container Host
DeleteAssetHistory Delete Asset
RemoveContainerHistory Delete Container
DeleteContainerRegistryHistory Delete Container Registry
DeleteDepartmentHistory Delete Department
DeleteConfigurationHistory Delete Environment
DeleteExportJobHistory Delete Export Job
DeleteGroupHistory Delete Group
DeleteImportJobHistory Delete Import Job
DeleteIpRangeHistory Delete Ip Range
DeleteNetworkHistory Delete Network
DeleteNetworkAdapterHistory Delete Network Adapter
DeleteNotificationRuleHistory Delete Notification Rule
DeleteProjectHistory Delete Project
DeletePublishedServiceHistory Delete Published Service
DeleteRoleHistory Delete Role
DeleteScheduleHistory Delete Schedule
DeleteSecondaryIpAddress Delete Secondary Ip
DeleteConfigurationTemplateHistory Delete Template
DeleteTunnelHistory Delete Tunnel
DeleteUserHistory Delete User
EndSessionHistory Delete Virtual Machines
DeleteVpnHistory Delete Vpn
DepartmentQuotaUpdateHistory Department Quota Update
DetachPublicIpAddressFromVmInterfaceHistory Detach Public Ip Address From Vm Interface History
DetachVpnHistory Detach Vpn
DisableLabelCategoryHistory Disable Label Category
DisableExecutionSequenceHistory Disable Vm Sequence
DisableVpnHistory Disable Vpn
DisconnectVpnHistory Disconnect Vpn
EditIpRangeHistory Edit Ip Range
EnableExecutionSequenceHistory Enable Vm Sequence
EnableVpnHistory Enable Vpn
ExportJobExpiredHistory Export Job Expired
FailedPublishSetLoginHistory Failed Sharing Portal Login
FailedUserLoginHistory Failed User Login
FinalizeScheduleHistory Finalize Schedule
GrantUserExportPermissionHistory Grant User Export Permission
GrantUserImportPermissionHistory Grant User Import Permission
ImportJobCompleteHistory Import Job Complete
ImportJobExpiredHistory Import Job Expired
ImportTemplateHistory Import Vm (Legacy)
LoginHistory Login
MergeConfigurationHistory Merge Environment
ModifyNotificationRuleHistory Modify Notification Rule
PasswordChangeHistory Password Change
HaltConfigurationHistory Power Off Environment
HaltConfigurationTemplateHistory Power Off Template
ProcessImportJobHistory Process Import Job
QuotaUpdateHistory Quota Update
PlatformRateLimitedActionHistory Rate Limited Action
ReleasePublicIpAddressHistory Release Public Ip Address
RenameContainerHistory RenameContainer
RemoveAllUsersFromAccessControl Remove All Users From Access
RemoveEntityFromAccessControl Remove Entity From Access
UnshareHistory Remove From Project
RemoveLabelHistory Remove Label
RemoveTagHistory Remove Tag
RemoveUserFromDepartmentHistory Remove User From Department
RemoveUserFromGroupHistory Remove User From Group
RestartConfigurationHistory Reset Environment
ResizeDiskAttemptHistory Resize Vm Disk
RevokeUserExportPermissionHistory Revoke User Export Permission
RevokeUserImportPermissionHistory Revoke User Import Permission
RunConfigurationHistory Run Environment
SendActivationLinkHistory Send Activation Link
SendNotificationHistory Send Notification
SetDefaultPublishSetSupportUrlHistory Set Default Sharing Portal Support Url
SetPublishSetSupportUrlNonDefaultHistory Set Sharing Portal Support Url Non Default
ShutdownConfigurationHistory Shutdown Environment
SsoLoginHistory Single Sign On Login
SuspendConfigurationHistory Suspend Environment
UpdateAccessControlPermission Update Access Control
UpdateAccessPolicyHistory Update Access Policy
UpdateAccountHistory Update Account
UpdateContainerRegistryHistory Update Container Registry
UpdateCsvExportHistory Update Csv Export
UpdateAutosuspendSettingHistory Update Default Power Options
UpdateDepartmentHistory Update Department
UpdateConfigurationAutosuspendHistory Update Environment Power Options
UpdateHardwareHistory Update Hardware
UpdateLabelCategoryHistory Update Label Category
UpdateNetworkAdapterHistory Update Network Adapter
UpdatePasswordPolicyHistory Update Password Policy
UpdateScheduleHistory Update Schedule
UpdateSsoPolicyHistory Update Sso Policy
UpdateUserHistory Update User
UpdateExecutionSequenceHistory Update Vm Sequence
UploadAssetHistory Upload Asset
UserQuotaUpdateHistory User Quota Update
VncSessionHistory Vnc Session

Operations on auditing reports

Generate an auditing report

Step 1: Create the report

POST https://cloud.skytap.com/auditing/exports.json

By default, your report will include activities in your account over the last 24 hours.

To filter your report or specify the reporting time period, include one or more optional report parameters in your POST request body (see Optional Report Parameters above). For example, to get the activity associated with a specific project during January 2017 and then have the report emailed to you, you could use the following request body:

{
    "project": "123456",
    "date_start": {
        "year": 2017,
        "month": 1,
        "day": 1,
        "hour": 0,
        "minute": 0
    },
    "date_end": {
        "year": 2017,
        "month": 1,
        "day": 31,
        "hour": 23,
        "minute": 59
    },
    "notify_by_email": true
}

Alternately, URL query parameters for the same request are formatted as

POST https://cloud.skytap.com/auditing/exports?project=123456&date_start%5Byear%5D=2017&date_start%5Bmonth%5D=1&date_start%5Bday%5D=1&date_start%5Bhour%5D=0&date_start%5Bminute%5D=0&date_end%5Byear%5D=2017&date_end%5Bmonth%5D=1&date_end%5Bday%5D=31&date_end%5Bhour%5D=23&date_end%5Bminute%5D=59&notify_by_email=true

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/auditing/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/auditing/exports/{export-id}.csv

    {
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/auditing/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/auditing/exports/{export-id}.csv

Response

The report is downloaded

Departments resource

A department is a top-level resource used to:

  • Map your organization’s internal departments or working groups into Skytap
  • Monitor and limit the resource usage of the department’s members

Notes

  • You must be a Skytap administrator to access the Departments resource.
  • All users (including non-administrator users) can view limits for their own departments. See List department limits.

Departments reference URI

https://cloud.skytap.com/departments

Departments resource model

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

Field Name Type Access Description
created_at string ro Date the department was created.
description string rw Optional description of department.
id integer ro Unique ID of department.
last_updated_by object ro Representation of the user who last updated the department.
name string rw Descriptive name of the department.
updated_at string ro Date the department was last updated.
url string ro Link to department’s details page.
user_count integer ro Number of users in the department.

Operations on departments

Get department description

Request

GET https://cloud.skytap.com/departments/{department-id}.json

Response

Representation of the department

List departments

Request

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

Scope, filter, sort, and paginate parameters

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

If you want to restrict or expand the results, you can add or edit the request parameters. For example, to return 50 results sorted by name, use the following request:

GET https://cloud.skytap.com/departments?count=50&offset=0&sort=name

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

Parameter name Type Descrtiption
sort string Sorts the list of departments either in ascending or descending order.
Options:
  • Sort by department name: name or name_desc
  • Sort by number of users: user_count or user_count_desc
  • Sort by date created: created_at_count or created_at_desc
  • Sort by date modified: updated_at or updated_at_desc
Response

Representation of departments in your account. The response will optionally include a Content-Range header and Link header.

  • Content-Range header: The Content-Range header lists the range of items you’re viewing, along with the total number of those items in your account. For instance, if your account has 40 departments, and you view departments 10-19, the Content-Range header will read items 10-19/40.
  • Link header: If you perform a GET command with a count less than your total number of departments, the collection will be paginated. A Link header will provide links with different offsets (e.g., </departments?count=10&offset=20>; rel=”next”, </departments?count=10&offset=0>; rel=”previous”); copying these will allow you to view other departments in the list.

Create department

Request

POST https://cloud.skytap.com/departments.json

{
    "name": "Sales",
    "description": "Sales employees."
}

Required and optional parameters

Required parameters
name Department name
Optional parameters
description Department description
Response

Representation of the new department

{
    "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/departments/{department-id}/users?count=10&offset=0

Scope, filter, sort, and paginate parameters

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

If you want to restrict or expand the results, you can add or edit the request parameters. For example, to return 50 standard users in the department sorted by last name, use the following request:

GET https://cloud.skytap.com/departments/users?count=50&offset=0&sort=last_name&query=account_role:standard_user

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

Parameter Name Type Description
sort string Sorts the list of department users either in ascending or descending order.Options:
  • Sort by user’s first name: first_name or first_name_desc
  • Sort by user’s last name: last_name or last_name_desc
  • Sort by user’s login name: login_name or login_name_desc
  • Sort by user’s last sign-in date: last_login or last_login_desc
  • Sort by user account role: account_role or account_role_desc
activated string Filters by the user’s account activation status. If true, the user account has been activated.
last_login string Filters by user’s last sign in.

Options:

  • In the past xdays: now-xd+to+now
  • In the past xmonths: now-xm+to+now
  • Not in the past xdays: to+now-xd
  • Custom: timestamp+to+timestamp
query string Filters results by various attributes; these are subfilters that can be separated by commas within the query parameter.
account_roleFilters results to display users in a specific user role. Options: admin, user_manager, standard_user, or restricted_user.
All AdminsFilters results to display users in a specific group (for example, `1234`).
project_idFilters results to display users in a particular project (for example, 1234). To filter by environments that aren't in a project, use none.
Response

Representation of department users.

Add users to department

Request

POST https://cloud.skytap.com/departments/{department-id}/users/{user-id}.json

or

POST https://cloud.skytap.com/departments/{department-id}/users.json

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

Representation of added users.

Users can belong to only one department. Users are automatically removed from their old department when they are added to a new department.

If this action would result in a quota violation, an error will be returned with details of the overages.

[
    {
        "id": "5678",
        "url": "https://cloud.skytap.com/users/5678",
        "first_name": "Peter",
        "last_name": "Kelly",
        "login_name": "Peter_Kelly",
        "email": "pkelly@internet.net",
        "title": "",
        "deleted": false,
        "can_add_resources": true,
        "account_role": "standard_user",
        "activated": true,
        "email_validated": true,
        "last_login": null,
        "sso_enabled": false,
        "department_name": "Sales",
        "department_id": "1234"
    }
]

Remove users from department

Request

DELETE https://cloud.skytap.com/departments/{department-id}/users/{user-id}

or

DELETE https://cloud.skytap.com/departments/{department-id}/users.json

{
    "user_ids": "123,124"
}

This removes a user or users from a department without assigning them to a new department; it doesn’t delete the users.

Response

Empty response body

List department limits

Request

GET https://cloud.skytap.com/departments/{department-id}/quotas

Note that this request is to the Department Quotas sub-resource, which is contained with the Department resource.

Response

List of limits defined for department. Includes the following fields:

Field Name Type Description
id string Name of the limit. One of concurrent_svms, concurrent_svms_power, concurrent_vms, storage, svm_hours, or svm_hours_power.
units string Unit of measure for the limit. For example, the unit for storage is MB.
limit integer The defined department limit. null is used for no limit.
usage integer Amount of the resource in use or consumed by department users.

Add, edit, or remove department limits

Request

By default, departments limits are set to null.

  • To add a limit, you can change null to a defined limit.
  • To delete a defined limit, you can change the defined limit to null.

The process for adding and removing a limit is the same as the process for editing a limit (see the sample request below).

PUT https://cloud.skytap.com/departments/{department-id}/quotas.json

[
    {
        "id": "svm_hours",
        "limit": 600
    }
]

Note that this request is to the Department Quotas sub-resource, which is contained with the Department resource.

Required parameters

id One of concurrent_svms, concurrent_svms_power, concurrent_vms, storage, or svm_hours. The svm_hours_power quota can’t be edited.
limit New limit.
Response

Representation of updated limit.

Delete department

Request

DELETE https://cloud.skytap.com/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/departments/exports

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

Initial response

Sample response body:

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

    {
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/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/departments/exports/123456.csv
Response

The report is downloaded.

Groups resource

A group is a top-level resource that represents a collection of users. A representation of a group will contain identifying information for the group (such as the group’s name), as well as representations of all the users in the group.

You must be a Skytap administrator or user manager to access the Groups resource.

Groups reference URI

https://cloud.skytap.com/groups/{group-id}

Groups resource model

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

Field Name Type Access Description
description string rw Optional description of group.
id integer ro Unique ID of group.
name string rw Descriptive name of the group.
url string ro Link to group’s details page.
users array rw Representation of users within the group .

Operations on groups

Get group description

Request

GET https://cloud.skytap.com/groups/{group-id}.json

Response

Representation of group.

List groups

Request

GET https://cloud.skytap.com/groups

Response

List of groups.

Create group

Request

POST https://cloud.skytap.com/groups.json

{
    "name": "Product 1 sales team",
    "description": "Sales employees working with Product 1."
}

Required and optional parameters

Required parameters
name Group name
Optional parameters
description Group description
Response

Representation of new group.

{
    "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/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/groups/{group-id}/users/{user-id}

Response

User is removed from group.

Delete group

Request

DELETE https://cloud.skytap.com/groups/{group-id}

Response

Group is deleted.

Export a groups report (.CSV)

Step 1: Create the report

POST https://cloud.skytap.com/groups/exports

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

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/groups/exports/123456",
    "notify_by_email": true,
    "email": "user@internet.net"
}
Step 2 (Optional): Download the report via the API

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

  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/groups/exports/123456.json

    {
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/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/groups/exports/123456.json

Response

The report is downloaded.

Inter-Configuration Network Routes (‘Tunnels’) 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) tunnels reference URI

https://cloud.skytap.com/tunnels/{tunnel-id}

Inter-Configuration Network Route (ICNR) tunnels resource model

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

Field Name Type Access Description
error string ro Describes any errors with the ICNR connection.
id string ro Identifier.
source_network network rw Source network from where the connection was initiated. This network doesn’t need to be “tunnelable” (visible to other networks).
status string ro Status of the tunnel.
target_network network rw Target network to which the connection was made. The network needs to be “tunnelable” (visible to other networks). To check the tunnelable attribute of this network, perform a GET request on the network resource (see Get Network Description).

Operations on ICNR tunnels

Get tunnel description

Request

GET https://cloud.skytap.com/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/tunnels.json

{
    "source_network_id": 111111,
    "target_network_id": 222222
}

Required parameters

source_network_id ID of the source network.
target_network_id ID of the target network. This network needs to be “tunnelable” (visible to other networks). To check the “tunnelable” attribute of this network, perform a GET request on the network resource (see Get Network Description).

Notes

  • source_network_id and target_network_id can't be the same.
  • If the source network is a manual network, it can't be connected to a NAT-enabled network
Response

Representation of the new tunnel.

{
    "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/tunnels/{tunnel-id}

Response

Tunnel is deleted

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

https://cloud.skytap.com/notifications/<notification-id>

Account-wide notification rules 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 Metered RAM hours usage against account, department, or user limits (as defined in the scope)
StorageNotificationRule Storage usage against account, department, or user limits (as defined in the scope)
ConcurrentVMNotificationRule Concurrent x86 Metered RAM usage against account, department, or user limits (as defined in the scope)
ConcurrentPowerVMNotificationRule Concurrent Power Metered RAM usage against account, department, or user limits (as defined in the scope)

Available only if your account is enabled for Power VMs.
IPAddressesUsedNotificationRule Public IP addresses usage against the account limit
NetworksUsedNotificationRule Networks in use against the account limit
VMUptimeNotificationRule VM running for more than N number of hours by all users or by select users (as defined in the scope)

threshold_amount

integer

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 reserved capacity.

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 aren’t valid for every rule type. See the table below.

subjects

array

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:
UserAn individual user (valid when scope is selected-users)
GroupA group of users defined in the account (valid when scope is selected-users)
DepartmentA department (valid when scope is selected-departments)
RegionA Skytap region (valid when scope is selected-regions-limit or selected-regions-quota)
id If the resource type is a user, group, or department, id is a string representation of the identifier (for example: '1234') for the resource. If the resource type is a region, the id is the name of the region (for example: US-West).
name The full name of the user, group, department, or region resource.

recipients

array

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:
UserAn individual user
GroupA group of users defined in the account
MetaRecipientA 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 Consumerthe consumer of the resource being monitored (e.g., owner of a VM)
All Adminsall Administrators in the account
All User Managersall User Managers in the account
All Standard Usersall Standard Users in the account

ordinal

integer

ro

Used internally by Skytap. Don’t write dependencies on this value.

The following table lists the scopes that are valid for each rule type.

Scroll the table to see all of the available options.

  customer-quota customer-limit all-users selected-users all-departments selected-departments all-regions-quota all-regions-limit selected-regions-quota selected-regions-limit
SVMHoursNotificationRule        
StorageNotificationRule
ConcurrentVMNotificationRule
ConcurrentPowerVMNotificationRule
IPAddressesUsedNotificationRule              
NetworksUsedNotificationRule              
VMUptimeNotificationRule                

Additionally…

  • customer-quota and customer-limit scopes are valid for monitoring Metered RAM hours in all accounts, and for monitoring concurrent Metered RAM, network, public IP address, and storage for accounts with global limits on these resources.
  • all-regions-quota, all-regions-limit, selected-regions-quota, and selected-regions-limit scopes are valid only for accounts with regional concurrent Metered RAM, network, public IP address, and storage limits.

Operations on notification rules

Get account-wide notification rule

Request

GET https://cloud.skytap.com/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/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/notifications.json

{
    "notification_rule": {
        "rule_type": "StorageNotificationRule",
        "threshold_amount": 50,
        "scope": "selected-users",
        "subjects": [
            {
                "type": "User",
                "id": "11"
            }
        ],  
        "recipients": [
            {
                "id": 2,
                "type": "MetaRecipient"
            }
        ]
    }
}
Required parameters
rule_type See the options in the Notifications resource model above.
threshold_amount See the options in the Notifications resource model above.
subjects If scope is selected-users, selected-departments, or selected-regions, you must include the id and type of the subjects being monitored.
recipients Include the id and type of the users who aren’tified when the event occurs.

You must be an administrator to perform this action.

Response

Status and the new rule in the response body.

{
    "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/notifications/{notification-id}

You must be an administrator to perform this action.

Response

Status only

Notification rules resource (user-defined)

User notification rules are created by an individual user to monitor their personal Metered RAM usage, storage usage, or the amount of time a VM has been running. The user is the only person notified when an event threshold is reached.

Notes

User notification rules reference URI

https://cloud.skytap.com/account/notifications/<notification-id>

User notification rules 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:
SVMHoursNotificationRuleMetered RAM hours usage against the user limit
StorageNotificationRuleStorage usage against the user limit
ConcurrentVMNotificationRuleConcurrent Metered RAM (x86) usage against the user limit
ConcurrentPowerVMNotificationRuleConcurrent Metered RAM (Power) usage against the user limit

Available only if your account is enabled for Power VMs.

VMUptimeNotificationRuleVM 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. Don’t write dependencies on this value.

Operations on user notification rules

Get user notification rule

Request

GET https://cloud.skytap.com/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/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/account/notifications.json

{
    "notification_rule": {
        "threshold_amount": "100",
        "rule_type": "StorageNotificationRule"
    }
}
Required parameters
rule_type See the options in the Notifications resource model above.
threshold_amount See the options in the Notifications resource model above.
Response

Status and the new rule in the response body.

{
    "id": "12345",
    "threshold_amount": 100,
    "rule_type": "StorageNotificationRule",
    "scope": "rule-owner",
    "ordinal": 323
}

Delete user notification rule

Request

DELETE https://cloud.skytap.com/account/notifications/{notification-id}

Response

Status only

Projects resource

Projects are an access permissions model used to share environments, templates, and assets with other users.

Projects reference URI

https://cloud.skytap.com/projects/{project-id}

Projects resource model

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

Field Name Type Access Description
auto_add_role_name string rw If this field is set to viewer, participant, editor, or manager, any new users added to your account are automatically added to this project at the specified project role. If the field is set to null, new users aren’t automatically added to the project. Existing users aren’t affected by this setting. For additional details, see Automatically adding new users to a project.
id integer ro Identifier.
name string rw User-defined project name.
show_project_members Boolean rw Determines whether projects members can view a list of other project members.
summary string rw User-defined description of project.
url URI ro URI reference for resource.

Operations on projects

Get project description

Request

GET https://cloud.skytap.com/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/projects

Response

Representation of projects. By default, the representation will display a limited number of fields.

Create project

Request

POST https://cloud.skytap.com/projects.json

{
    "name": "QA Project"
}
Response

Representation of newly created project

Edit project’s settings

Request

PUT https://cloud.skytap.com/projects/{project-id}

Response

Updated representation of project.

List Users Associated with a Project

Request

GET https://cloud.skytap.com/projects/{project-id}/users.json

Response

Representation of users in the project

View users or groups in project

Request

GET https://cloud.skytap.com/projects/{project-id}/users/{user-id}.json

GET https://cloud.skytap.com/projects/{project-id}/groups/{group-id}.json

Response

Representation of user or group (including project roles)

Add user or group to project

Request

POST https://cloud.skytap.com/projects/{project-id}/users/{user-id}?role={account_role}

POST https://cloud.skytap.com/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).

Edit user or group’s project role
Request

PUT https://cloud.skytap.com/projects/{project-id}/users/{user-id}?role={account_role}

PUT https://cloud.skytap.com/projects/{project-id}/groups/{group-id}?role={account-role}


role One of viewer, participant, editor, or manager.
Response

Updated representation of user or group (including project role).

Change project owner

Request

PUT https://cloud.skytap.com/projects/{project-id}.json

{
    "owner": 1234
}
owner User ID of the new project owner.
Response

Updated representation of the project.

List environments, templates, or assets in project

Request

GET https://cloud.skytap.com/projects/{project-id}/configurations

GET https://cloud.skytap.com/projects/{project-id}/templates

GET https://cloud.skytap.com/projects/{project-id}/assets

Response

List of resources in project

Add environment, template, or asset to project

Request

POST https://cloud.skytap.com/projects/{project-id}/configurations/{configuration-id}

POST https://cloud.skytap.com/projects/{project-id}/templates/{template-id}

POST https://cloud.skytap.com/projects/{project-id}/assets/{asset-id}

Response

Status

Remove environment, template, or asset from project

Request

DELETE https://cloud.skytap.com/projects/{project-id}/configurations/{configuration-id}

DELETE https://cloud.skytap.com/projects/{project-id}/templates/{template-id}

DELETE https://cloud.skytap.com/projects/{project-id}/assets/{asset-id}

Response

Status

Delete project

Request

DELETE https://cloud.skytap.com/projects/{project-id}

Response

Status

Public IPs resource

Public IP resources represent static that can be used to route network traffic to VMs over the Internet or as an endpoint for VPNs.

Public IPs reference URI

https://cloud.skytap.com/ips

Public IPs resource model

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

Field Name Type Access Description
address string ro Unique IPv4 public IP address.
id string ro ID of the public IP address (same as address).
nics array ro Representation of attached network adapters, if any. Includes network adapter id and deployed status.
region string ro Region that the resource is housed in (for example, US-West).
vpn_id string ro ID of attached VPN, if any.
If not attached to a VPN, null.

Operations on public IPs

List static public IP addresses

Request

GET https://cloud.skytap.com/ips.json

Filter parameters

An optional region parameter can be used to filter the list of public IP addresses by region. For example, to see a list of public IP addresses in US-West:

GET https://cloud.skytap.com/ips?region=US-West

This request can only be made by administrators.

Response

Representation of public IP addresses in the account.

Get public IP address description

Request

GET https://cloud.skytap.com/ips/{public_ip_address}.json

Response

Representation of public IP

Acquire static public IP

Request

POST https://cloud.skytap.com/ips/acquire.json

{
    "region": "US-West"
}

Required parameters

region One of APAC-2, AU-Sydney-I-1, CAN-Toronto, CN-HongKong-M-1, DE-Frankfurt-1-1, EMEA, IE-Dublin-M-1, IN-Pune-M-1, NL-Amsterdam-M-1, SG-Singapore-M-1, UK-Londond-M-1, US-Central, US-East-2, US-Texas-M-1, US-Virginia-M-1, or US-West

This request can only be made by administrators.

Response

Representation of newly-acquired public IP address.

Release static public IP address

Request

POST https://cloud.skytap.com/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/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 Adapters resource.

Schedules resource

A schedule is a set of one or more automated actions applied to an environment or template. This resource functions identically to the schedules created in the Schedules tab in Skytap’s web interface. All operations that can be performed on schedules from the Schedules tab can also be performed and automated via operations on the schedules resource in the API.

For more information, see Automating Actions with Schedules.

Schedules reference URI

The schedules reference URI is as follows:

https://cloud.skytap.com/schedules/<schedule-id>

Schedules resource model

The element name is schedules and the following fields are defined.

Schedules can be assigned to both templates and environments; some fields are unique to each resource type. These will be covered in separate tables below.

When a schedule is applied to a template, an environment will first be created from that template and all scheduled actions will apply to that environment.

Field Name Type Access Description
actions array rw Array of objects comprising all schedules actions in a schedule, with the exception of actions that can’t recur, such as creating or deleting an environment. Each object has two attributes, with the exception of the save object, which can have three:
  • type – A string that is one of the allowed action types: run, suspend, shut down, power off, or save.
  • offset – An integer equal to the number of seconds after start that this action will take place. For instance, if the action was scheduled to start two hours after the schedule was executed, the offset would be 7200.
  • live_copy – A Boolean that enables save for running VMs (without requiring a previous suspend, shut down, or power off action).
delete_at_end Boolean rw If end_at is set, this Boolean determines whether the schedule’s environment is deleted when the time specified in end_at is reached.
end_at string 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.
executions array 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.
id string ro Unique identifier for schedule.
next_action_name string ro The name of the next action that will execute as part of the schedule. This can be one of the legal actions (above), start (if the schedule hasn’t yet executed), or delete (if all scheduled actions have completed, end_at has a value, and delete_at_end is set as true).
next_action_time string ro The time when the next action (specified in next_action_name, above) will occur. The format is YYYY/MM/DD hh:mm.
notify_user Boolean rw Determines whether the schedule’s owner receives an email after the completion of a successful action. The user will always be notified when an action fails to complete, even if notify_user isn’t enabled.
recurring_days array 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.
region string ro Region that the resource is housed in (for example, US-West).
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.
time_zone string rw The time zone in which the scheduled action will run. Entered as English strings, e.g. Mumbai or Pacific Time (US & Canada). For a list of time zones, see Time Zones and UTC Offsets.
title string rw User-defined name of the schedule. Limited to 256 characters.
user object 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
url string ro Full URL for schedule.

Environment fields

These fields only apply to schedules operating on environments.

Field Name Type Access Description
configuration_id string ro The ID of the environment the schedule is applied to (e.g., 123).
configuration_name string ro A string representing the name of the environment the schedule is applied to.
configuration_url string ro The URL of the environment the schedule schedule applies to, ending with the ID number. If the ID is 123, the URL will be https://cloud.skytap.com/configurations/123.

Template fields

These fields only apply to schedules operating on templates.

Field Name Type Access Description
append_timestamp_to_name Boolean rw Determines whether a timestamp will be appended to the new environment’s name. This timestamp will reflect the date and time that the configuration was created.
new_configuration_name string rw Name of the environment that will be created from the target template once the schedule is started.
template_id string ro The numerical ID of the template that the schedule is applied to.
template_name string ro User-defined name of the template the schedule is applied to.
template_url string ro The URL of the template the schedule applies to, ending with the ID number (e.g., https://cloud.skytap.com/templates/123).
vm_ids array rw An array of VM IDs for newly-created environment.

Operations on schedules

Get a schedule description

Request

GET https://cloud.skytap.com/schedules/{schedule-id}.json

Response

Representation of the schedule.

List schedules

Request

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

Scope, filter, sort, and paginate parameters

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

By default, the API will return a list of schedules that you own.

If you want to restrict or expand the results, you can add or edit the request parameters. For example, to return a list of 50 schedules owned by all users in the account, change the count to 50 and include &scope=admin.

GET https://cloud.skytap.com/schedules?count=50&offset=0&scope=admin

For a list of optional parameters, see the table below:

Parameter Name

Type

Description

scope

string

Filters or expands the list of schedules. Options:

admin Displays schedules created by anyone (available to admins only)
admin&query=<user_id> Display schedules owned by a particular user (available to admins only)

query

string

Filters results by various attributes

configuration_id Lists schedules that contain a specific environment; includes environments owned by other users in your customer account (for example: query=configuration_id:12345)

You must have access to the environment to use this query.
template_id Lists schedules that contain a specific template; includes templates owned by other users in your customer account (for example: query=template_id:11111)

You must have access to the template to use this query.

sort

string

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

  • Sort by environment and/or template name (resource): configuration_name or configuration_name_desc
  • Sort by owner: user_id or user_id_desc
  • Sort by schedule name (title): title or title_desc
  • Sort by date and time of the next action: next_action_time or next_action_time_desc
Response

The response will optionally include a Content-Range header and Link header.

  • Content-Range header: The Content-Range header lists the range of items you’re viewing, along with the total number of those items in your account. For instance, if your account has 40 schedules, and you view schedules 10-19, the Content-Range header will read items 10-19/40.
  • Link header: If you perform a GET command with a count less than your total number of schedules, the collection will be paginated. A Link header will provide links with different offsets (e.g., </schedules?count=10&amp;offset=20>; rel="next", </schedules?count=10&amp;offset=0>; rel="previous"); copying these will allow you to view other schedules in the list.

Create a schedule

Request

POST https://cloud.skytap.com/schedules.json

{
    "title": "My New Schedule",
    "template_id": "123456",
    "new_configuration_name": "New Environment",
    "actions": [
            {
                "type": "run",
                "offset": "3600"
            },
            {
                "type": "save",
                "offset": "7200"
                "live_copy": true
            }
        ],
    "start_at": "2013/09/09 09:00",
    "time_zone": "Pacific Time (US & Canada)"
}

Required and optional parameters

Required parameters
title Schedule name
configuration_id (or template_id) ID of the environment or template the schedule is based on
start_at In the format YYYY/MM/DD hh:mm
time_zone For a list of time zones, see Time Zones and UTC Offsets.
Optional parameters

If you want to assign actions to the schedule during the POST, include an actions array, with type and offset defined. Optionally, include live_copy to save running VMs.

type One of run, suspend, shut down, power off, and save.
offset The number of seconds after start that this action will take place
live_copy (optional save parameter) Enables save for running VMs (without a previous suspend, shut down, or power off action). Either true or false. If this parameter is omitted, it is interpreted as false.

Notes

  • In XML, you must specify a type attribute of "array" for Actions (<actions type = "array">…</actions>). Specifying this type isn’t necessary for JSON.
  • If you include live_copy, we strongly recommend that you ensure that VM activity is quiesced before the save action.
Response

Representation of the new schedule

Delete a schedule

Schedules are automatically deleted after the schedule completes. To delete a schedule before it completes, use the following request:

Request

DELETE https://cloud.skytap.com/schedules/{schedule-id}.json

Response

Status

Usage reports resource

The usage report resource represents a report of all account resource usage within a designated period. When generating the report, you can select:

  • The usage metric you want to generate reports on
  • How you want the report to be displayed
  • The reporting time period

Report request limits

Skytap limits the number of concurrent report requests:

  • 1,000 per account
  • 100 per user

Most requests (Skytap UI or API) persist for 15 minutes. Reports requested via “Email CSV” persist for one week.

The report response is limited to 5,000 report entries. For reports larger than 100 5,000 report entries, use CSV export to download results.

You must be a Skytap administrator to request usage reports.

Usage reports reference URI

https://cloud.skytap.com/reports

Usage reports resource model

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

Not all fields are returnd for all customers.

Field Name Type Access Description
aggregate_by string rw Determines the increments in which data is displayed. One of month, day, or none. none displays activity as a lump sum in that period.
Reports grouped by raw must use none for aggregation.
email string ro Email address the report will be sent to; this is the email address of the API user.
end_level integer ro Amount of concurrent Metered RAM in use at the end of the report period selected.
group_by string rw How usage data is grouped.
One of user, group, region, department, or raw.
user is the default.
high_count integer ro Maximum number of VMs running at the highest point in the report period (peak).
high_date string ro Point in time at which the high_level value was achieved.
high_level integer ro Maximum amount of concurrent Metered RAM running at the highest point in the report period (peak).
high_level_above_subscription string ro Amount of concurrent Metered RAM above the reserved capacity at the highest point in the report period.
id integer ro ID of usage report.
label_type string rw One of none , single, or all:
noneNo label data will be included in the report.
singleSingle value labels will be included in the report.
allSingle and multiple value labels will be included in the report.

Labels are only available for ungrouped reports. If label_type is single or all, group_by will automatically be set to raw.
low_date string ro Point in time at which the low_level value was achieved.
low_level integer ro Amount of concurrent Metered RAM running at the lowest point in the report period.
notify_by_email Boolean rw If true, the report will be emailed to you when it’s complete (CSV report only).
ready Boolean ro If true, the report is ready for access.
region string rw Region to report usage on (for example, US-West). all is the default.
resource_type string rw Type of resource usage to report.
One of storage , svms, or svms_power:
storageStorage usage will be reported.
svmsCumulative Metered RAM usage and max concurrent Metered RAM usage for x86 VMs will be reported. svms is the default.
svms_powerCumulative Metered RAM usage and max concurrent Metered RAM usage for Power VMs will be reported.
results_format string rw File format of the report. One of csv or json.
start_date
end_date		 string rw Start and end date for data collection period. Either YYYY/MM/dd HH:mm:ss format or ISO 8601 format (2013-03-21T01:00:00.000Z). If blank, the report will include usage from the current calendar month.
Usage data is available from the past two years. If the start_date or end_date is outside of this period, the report may include partial data or no data.
start_level integer ro Amount of concurrent Metered RAM in use at the beginning of the report period selected.
total_concurrent_overage string ro Number of Metered RAM hours charged to the account.
total_usage string ro Total number of Metered RAM hours used by the account.
url string ro URL where the report can be accessed.
utc Boolean rw If true, the report will use the UTC time zone.
If false, the report will use the admin’s local time zone. False is the default.

Operations on usage reports

Create CSV usage report

Request
Step 1: Request to create usage report

POST https://cloud.skytap.com/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.

  3. When "ready": true, you can access the report at the report URL listed in the response body.

    Sample request:

    GET https://cloud.skytap.com/reports/{report-id}.csv

Response

The report is downloaded.

Required parameters
title Schedule name
configuration_id (or template_id) ID of the environment or template the schedule is based on
start_at In the format YYYY/MM/DD hh:mm
time_zone For a list of time zones, see Time Zones and UTC Offsets.
Optional parameters

If you want to assign actions to the schedule during the POST, include an actions array, with type and offset defined. Optionally, include live_copy to save running VMs.

type One of run, suspend, shut down, power off, and save.
offset The number of seconds after start that this action will take place
live_copy (optional save parameter) Enables save for running VMs (without a previous suspend, shut down, or power off action). Either true or false. If this parameter is omitted, it is interpreted as false.

Notes

  • In XML, you must specify a type attribute of "array" for Actions (<actions type = "array">…</actions>). Specifying this type isn’t necessary for JSON.
  • If you include live_copy, we strongly recommend that you ensure that VM activity is quiesced before the save action.

Users resource

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

Notes

  • You must be a Skytap administrator or user manager to create and manage users.
  • All users can see can view their own user limts. See List user limits.

Users reference URI

https://cloud.skytap.com/users

Users resource model

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

Field Name Type Access Description
account_role string rw Defines the user’s access to features and settings. One of:
  • restricted_user
  • standard_user
  • user_manager
  • admin

For more information on user roles, see User Roles and Access Permissions.
activated Boolean ro Indicates whether the user has activated his or her account.
assets array ro Array of assets that the user owns.
can_import Boolean rw for user accounts
ro for admin accounts		 Determines if a restricted user, standard user, or user manager can import VMs. By default, this is set to false for user accounts. Administrator accounts have this value locked to true.
can_export Boolean rw for user accounts
ro for admin accounts		 Determines if a restricted user, standard user, or user manager can export VMs. By default, this is set to false for user accounts. Administrator accounts have this value locked to true.
configurations array ro Array of environments that the user owns.
created_at timestamp ro Date and time that the user account was created.
default_region string rw Default region used for VM imports, asset uploads, new VPNs, and new public IP addresses.
id string ro Identifier.
email string rw Email address to which notifications may be sent. Not validated at submit time.
first_name string rw First name string used for display in the UI. Not validated for uniqueness.
has_public_library Boolean rw Determines if a user or administrator can access public templates and public assets owned by Skytap. By default, this value is true.
last_name string rw Last name string used for display in the UI. Not validated for uniqueness.
login_name string rw Sign-in name for the user.
password string wo The password field is write-only. A new password can be sent with this field, but it will always be returned as the special value ****.<br>If ******** is sent as the value of the password element, it’s ignored; the current password won’t be changed.
promiscuous Boolean rw Indicates whether the user can edit the promiscuous mode setting on network adapters.By default, this is set to false.This field will be visible if promiscuous mode permissions are enabled for the customer account; otherwise, this field is hidden. For more information, see Enabling Promiscuous Mode on a Network Adapter.
quotas array ro These are read-only within the Users resource; user limits must be updated directly via the User Quota sub-resource (https://cloud.skytap.com/users/12345/quotas).
For more information, see List user limits, Create user limit, Edit user limit, and Delete user limit.
sso_enabled Boolean rw This field will only appear if your customer account is enabled for single sign-on, or SSO. If set to false, this is a standard Skytap user account; if set to true, the account will use SSO to sign in to Skytap.
templates array ro Array of templates that the user owns.
time_zone time zone rw Time zone associated with the user’s account. For a list of time zones, see Time Zones and UTC Offsets.
title string rw Optional text field for user title.
url URI ro URI reference for the user.

Operations on users

Get user description

Request

GET https://cloud.skytap.com/users/{user-id}.json

Response

A user element.

List users

Request

GET https://cloud.skytap.com/users

Response

A list of user elements.

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

Create user

Request

POST https://cloud.skytap.com/users.json

{
    "login_name": "corrina_corrina",
    "email": "corrina@internet.com",
    "account_role": "restricted_user"
}

login_name and email are required. If account_role isn’t specified, the user will be created as a standard user.

Response

Representation of the new user.

Edit user

Request

PUT https://cloud.skytap.com/users/{user-id}?{attr-name}={attr-value}

Not all attributes are modifiable.

Response

Updated user element.

Get a list of environments, templates, or assets owned by the user

Request

GET https://cloud.skytap.com/users/{user-id}.json

Response

The list of environments, templates, and assets owned by the user is included in the representation of the user.

{
   "id": "1234",
   "url": "https://cloud.skytap.com/users/1234",
   "login_name": "sample_user",
   "first_name": "Sample",
   "last_name": "User",
   "title": "",
   "email": "user@sample.com",
   "default_region": "US-West",
   "created_at": "2018-04-22T15:34:16-07:00",
   "deleted": false,
   "activated": true,
   "password": "\*\*\*\*\*\*\*\*\*\*",
   "account_role": "standard_user",
   "quotas": [
       {
           "id": "concurrent_vms",
           "quota_type": "concurrent_vms",
           "units": "integer",
           "limit": null,
           "region": "global",
           "usage": 0,
           "readonly": false
       },
       {
           "id": "concurrent_svms",
           "quota_type": "concurrent_svms",
           "units": "integer",
           "limit": null,
           "region": "global",
           "usage": 0,
           "readonly": false
       },
       {
           "id": "cumulative_svms",
           "quota_type": "cumulative_svms",
           "units": "hours",
           "limit": null,
           "region": "global",
           "usage": 0,
           "readonly": false
       },
       {
           "id": "concurrent_svms_power",
           "quota_type": "concurrent_svms_power",
           "units": "integer",
           "limit": null,
           "region": "global",
           "usage": 0,
           "readonly": false
       },
       {
           "id": "cumulative_svms_power",
           "quota_type": "cumulative_svms_power",
           "units": "hours",
           "limit": null,
           "region": "global",
           "usage": 0,
           "readonly": true
       },
       {
           "id": "concurrent_storage_size",
           "quota_type": "concurrent_storage_size",
           "units": "MB",
           "limit": null,
           "region": "global",
           "usage": 112702,
           "readonly": false
       }
   ],
   "configurations": [
       {
           "id": "12345",
           "url": "https://cloud.skytap.com/configurations/12345",
           "name": "Ubuntu testing",
           "error": "",
           "container_hosts_count": 0,
           "shutdown_on_idle": null,
           "shutdown_at_time": null
       },
       {
           "id": "12346",
           "url": "https://cloud.skytap.com/configurations/12346",
           "name": "Web app with audio - demo",
           "error": "",
           "container_hosts_count": 0,
           "shutdown_on_idle": 7200,
           "shutdown_at_time": null
       }
   ],
   "templates": [
       {
           "id": "222222",
           "url": "https://cloud.skytap.com/templates/222222",
           "name": "Web app template",
           "region": "US-West",
           "region_backend": "skytap",
           "container_hosts_count": 0
       }
   ],
   "assets": [
       {
           "id": "1245",
           "name": "jre-8u25-linux-i586.gz",
           "url": "https://cloud.skytap.com/assets/1245",
           "region": "US-West",
           "size": 64545312
       }
   ],
   "can_export": false,
   "can_import": false,
   "promiscuous": false,
   "report_access": "customer",
   "classrooms_access": null,
   "time_zone": "Pacific Time (US & Canada)",
   "has_public_library": true
}

List user limits

Request

GET https://cloud.skytap.com/users/{user-id}/quotas.json

Note that this request is to the User Quotas sub-resource, which is contained with the User resource.

Response

List of limits defined for user. Includes the following fields:

Parameter Name Type Description
id integer Name of the limit. One of concurrent_svms, concurrent_svms_power, concurrent_vms, concurrent_storage_size, cumulative_svms, or cumulative_svms_power.
quota_type string The resource the limit is measuring.
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/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 quota_type orid values.
  • The cumulative_svms_power and svm_hours_power quota can't be edited.
  • This request is to the User Quotas sub-resource, which is contained with the User resource.
Response

Representation of the new limit.

Edit user limit

Request

PUT https://cloud.skytap.com/users/{user-id}/quotas/{quota-type}?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/users/{user-id}/quotas/{quota-type}

Note that this request is to the User Quotas sub-resource, which is contained with the User resource.

Response

Status

Edit report access

Request

PUT https://cloud.skytap.com/users/{user-id}?report_access={value}

Report access permits non-administrator users to create and view reports.

Valid values for report_access are:

customer the user can create and view reports for the full account.
department the user can create and view reports only for the department to which the user belongs.

Notes

  • Only administrators can grant report_access.
  • By default, administrators always have account-wide report_access.
  • report_access can't be granted to restricted users.
Response

Status

Delete user

Request

DELETE https://cloud.skytap.com/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/users/exports

Include a request body indicating the type of report you want.

  • To export a quick report, include a “quotas”: false parameter.
  • To export a full report, include a “quotas”: true parameter.
  • To have the report emailed to you, include a “notify_by_email”: true parameter.

For more information about these reports, see Generating User Reports.

{
    "quotas": false,
    "notify_by_email": true
}
Initial response

Sample response body:

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

    {
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/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/users/exports/123456.csv
Response

The report is downloaded.

VM exports resource

An export represents a single export job. Each export starts with a VM contained in a template owned by the user.

Exports reference URI

https://cloud.skytap.com/exports/{export-id}

Exports resource model

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

Field Name Type Access Description
errors string ro Describes the error (when status contains error).
expiration_date string ro Date when export job will be deleted.
filename string ro File name created by Skytap, present in FTP URL.
ftp_host string ro Host name of FTP.
ftp_password string ro Password for FTP sign in.
ftp_url string ro Download location for VM image.
ftp_user_name string ro User name for FTP sign in.
id string ro Reference ID for the export job.
template_name string ro Name of source template.
status string ro Can equal one of four states:
completeWhen the export is complete, the status reads complete.
errorIf an error occurs, the status reads error and the error details display in the errors field.
newThe status is new upon initial creation.
processingThe VM is being exported.
template_url string ro URL of source template.
user string ro Array representing a user, same as in “import” resource.
vm_name string ro Name of source VM.
vm_url string ro URL of source VM.

Operations on exports

Get export jobs

Request

GET https://cloud.skytap.com/exports.json

Filter parameters

By default, the response will only contain export jobs that you own. If you’re an admin, you can see all of the export jobs in the account by including an admin=true parameter. For example:

GET https://cloud.skytap.com/exports?admin=true

Response

Representation of the export jobs.

Create a VM export

Request

POST https://cloud.skytap.com/exports.json

{
    "vm_id": "12345"
}

Required parameters

vm_id ID of the VM you want to export; the VM must be within a template.
Response

Representation of new export job.

Get VM export status

Request

GET https://cloud.skytap.com/exports/{export-id}.json

Response

Representation of status field.

Delete VM export

Request

DELETE https://cloud.skytap.com/exports/{export-id}

Response

The export file will be deleted from the Skytap FTP server.

VM imports resource

An import represents a single import job. Each import job imports one or more VM images and their associated networks; these are added to a new Skytap environment. If no networks are defined, Skytap creates a single automatic network for the environment.

Importing is a multi-step process:

  1. Create a New Import Job.
  2. Upload the VM files to the Skytap SFTP site, IBM Cloud Object Storage bucket, or Microsoft Azure Blob Storage container. FTP uploads must be completed outside of the API, using an SFTP client. For FTP uploads, Skytap provides the SFTP site hostname and access credentials in the response body for the request to create a new import job.
  3. Start the Import.
  4. Get the Import Status; you will also be notified via email when the import is complete.

Imports reference URI

https://cloud.skytap.com/imports/{import-id}

Imports resource model

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

Field Name Type Access Description
configuration_url string ro This field doesn’t exist until the “status” field equals “complete.” At this point, this field will contain the URL for the new Skytap environment.
errors string ro Describes general import errors (when status contains error). General import errors include mismatched MD5 checksums, unsupported file type, missing files, and import jobs that would exceed the user’s storage limit.
expiration_date timestamp ro Date import job will be deleted.
ftp_host string ro SFTP host name. Ignored for IBM or AZURE imports.
ftp_password string ro Password for SFTP sign in. Ignored for IBM or AZURE imports.
ftp_url string ro The full SFTP path to the upload repo:
sftp://<sftp-username-ref><sftp-password-ref>@<hostname-ref>/upload/
Ignored for IBM or AZURE imports.
ftp_user_name string ro User name for SFTP sign in. Ignored for IBM or AZURE imports.
id string ro Reference ID for import job.
includes_power Boolean rw Set to true for imports that include Power A CPU architecture that supports IBM i, AIX, and Linux (on Power) in Skytap. VMs.
is_released Boolean ro Completion status of the import job. If true, the import job is done and no more VMs can be uploaded for this import job.
provider string rw The source location from which VMs should be imported. Either FTP, AZURE or IBM. If no value is provided, FTP is assumed.
provider_parameters string rw Connection parameters for VM import source. Mbr>
FTP
Field NameTypeAccessDescription
user_namestringroUser name for SFTP sign in.
passwordstringroPassword for SFTP sign in.
hostURIroSFTP host name.
urlURIroThe full SFTP path to the upload repo.
AZURE
Field NameTypeAccessDescription
container_namestringrwThe Azure Blob Storage containter name.
connection_stringstringrwThe Azure Blod Storage connection string.
IBM
Field NameTypeAccessDescription
bucket_namestringrwThe name of the IBM Cloud storage bucket.
resource_crnstringrwThe CRN of the IBM Cloud storage bucket.
locationstringrwThe IBM Cloud location of the bucket.
api_keystringrwThe IBM Cloud storage API key.
– OR –
hmac_keysarrayrwThe IBM Cloud storage HMAC credentials.
Field NameTypeAccessDescription
access_key_idstringrwThe IBM Cloud storage HMAC access key ID..
secret_access_keystringrwThe IBM Cloud storage HMAC secret access key.
region string rw Region where the template will be stored. One of APAC-2, AU-Sydney-I-1, CAN-Toronto, CN-HongKong-M-1, DE-Frankfurt-1-1, EMEA, IE-Dublin-M-1, IN-Pune-M-1, NL-Amsterdam-M-1, SG-Singapore-M-1, UK-Londond-M-1, US-Central, US-East-2, US-Texas-M-1, US-Virginia-M-1, or US-West. Use the location closest to the majority of your users. If no region is specified, the import will default to US-West.
region_backend string rw Region that the resource is housed in (for example, US-West).
md5 string 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)
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.
template_name string rw Name of environment to be created; required for all imports.
user string ro Array defining the user who created the import. Includes:
  • id
  • url
  • login_name
  • first_name
  • last_name
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 imports

Get import jobs

Request

GET https://cloud.skytap.com/imports.json

Filter parameters

  • By default, the response will only contain import jobs that you own. If you’re an admin, you can see all of the import jobs in the account by including an admin=true parameter. For example:

      GET https://cloud.skytap.com/imports?admin=true

  • An optional region parameter can be used to filter the list of import jobs by region. For example, to see a list of imports in US-West:

      GET https://cloud.skytap.com/imports?region=US-West
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/imports.json

{
    "template_name": "name of environment",
    "region": "US-West",
    "md5": "MD5 (ExportedVM.7z) = cbde87673443077ce053fc57ec4ea8ec"
}

Required and optional parameters

Required parameters
template_name Name of the new environment
provider The source location from which VMs should be imported. Either FTP, AZURE or IBM. If no value is provided, FTP is assumed.
provider_parameters Connection parameters for VM import source.
FTP
Field NameDescription
user_nameUser name for SFTP sign in.
passwordPassword for SFTP sign in.
hostSFTP host name.
urlThe full SFTP path to the upload repo.
AZURE
Field NameDescription
container_nameThe Azure Blob Storage containter name.
connection_stringThe Azure Blod Storage connection string.
IBM
Field NameDescription
bucket_nameThe name of the IBM Cloud storage bucket.
resource_crnThe CRN of the IBM Cloud storage bucket.
locationThe IBM Cloud location of the bucket.
api_keyThe IBM Cloud storage API key.
– OR –
hmac_keysThe IBM Cloud storage HMAC credentials.
Field NameDescription
access_key_idThe IBM Cloud storage HMAC access key ID.
secret_access_keyThe IBM Cloud storage HMAC secret access key.
Optional parameters
region Name of the region to upload to. If no region is specified, your default region (in your user settings) is used.
md5 MD5 checksum. For more information about the valid formats, see Creating MD5 hash values for VM imports.
includes_power Either true or false. Can be used only if Power VMs are enabled for your account. If true, Skytap checks that the region supports Power VMs; Skytap presents an error prior to processing the import if Power VMs aren’t supported in that region.
Response

Representation of the new import, including the hostname, user name, and password needed to upload the VM files to the SFTP server.

Start the import

Request

After uploading the VM files to the SFTP server, start the import with the following request:

PUT https://cloud.skytap.com/imports/{import-id}.json

{
    "status": "processing"
}
Response

Representation of resource with updated status field.

Get the import status

Request

GET https://cloud.skytap.com/imports/{import-id}.json

Response

Representation of status field.

Delete import

Request

DELETE https://cloud.skytap.com/imports/{import-id}

Response

The import job and site will be deleted from Skytap’s SFTP server. The environment created from the import won’t be affected.

WANs resource

The WANs resource contains two types of network connections:

  • VPN: a Virtual Private Network (VPN) is an IPsec network tunnel that securely connects networks in your Skytap account to another network over the public Internet.
  • Skytap on Azure ExpressRoute connection: Skytap on Azure ExpressRoute connection is a dedicated, secure network tunnel between a Skytap environment and an Azure virtual network, available to Skytap on Azure accounts.

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

Notes

  • At this time, the API supports create, read, update, and delete actions on VPNs, and limited view and edit actions on Skytap on Azure ExpressRoute connections. For help with creating or editing a Skytap on Azure ExpressRoute connection, contact support@skytap.com
  • You must be an administrator to perform most actions on WAN resources.

Creating a VPN is a multi-step process:

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

Connecting a virtual network to a WAN is a multi-step process:

  1. Attach a network to a WAN
  2. Connect the attached network to a WAN

WANs reference URI

https://cloud.skytap.com/vpns/{vpn-id}

Notes

  • Throughout the Skytap API, WANs (VPN or Skytap on Azure ExpressRoute connection) are referred to as VPNs. Skytap has modified the VPNs resource to include both VPNs and Skytap on Azure ExpressRoute connections.
  • The {vpn-id} must include the vpn- prefix.

WANs resource model

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

Most of these fields are read-only for Skytap on Azure ExpressRoute connections.

Field Name Type Access Description
attached_network_count integer ro The number of networks attached to the WAN.

Visible only to administrators.
connected_network_count integer ro The number of networks connected to the WAN.

Visible only to administrators.
connection_type string ro The type of WAN. Either vpn or express_route.
vpn is a Virtual Private Network; express_route is an Skytap on Azure ExpressRoute connection connection.
dpd_enabled Boolean rw for VPNs, ro for Skytap on Azure ExpressRoute connections If true, Dead Peer Detection is enabled.

Visible only to administrators.
enabled Boolean rw for VPNs, ro for Skytap on Azure ExpressRoute connections If true, the WAN is enabled.
error string ro If there’s an error, this field contains information about the error. Otherwise, it’s blank.

Visible only to administrators.
id string ro Identifier, in the form vpn-#.
internet_key_exchange string rw for VPNs, ro for Skytap on Azure ExpressRoute connections Internet Key Exchange version associated with the WAN.
One of ikev1 or ikev2

Visible only to administrators.
local_peer_ip string rw for VPNs, ro for Skytap on Azure ExpressRoute connections Public IPv4 address associated with the WAN (must be an available Skytap public IP address).

Visible only to administrators.
local_subnet string rw for VPNs, ro for Skytap on Azure ExpressRoute connections Range of Skytap IP addresses routed through tunnel.
IPv4 address range.
maximum_segment_size string rw for VPNs, ro for Skytap on Azure ExpressRoute connections A maximum segment size can be implemented to resolve certain errors. This setting should not be enabled unless your IT organization or Skytap Support instructs you to do so. Valid range: 536 to 1460.

Visible only to administrators.
name string rw The user-defined name for the WAN. Limited to 255 characters. UTF-8 character type.
nat_local_subnet Boolean rw for VPNs, ro for Skytap on Azure ExpressRoute connections If true, the WAN is NAT-enabled.
nat_pool_remaining integer ro Remaining assignable IP addresses for NAT.

Appears only if nat_local_subnet is true.
nat_pool_size integer ro Total size of IP address pool for NAT.

Appears only if nat_local_subnet is true.
network_attachments array ro A representations of the relationships between this WAN and any networks attached to it, including whether the network is currently connected. To view this array, make a GET request to GET https://cloud.skytap.com/vpns/&amp;lt;vpn-id&amp;gt;.
Related: Network Resource.

Visible only to administrators.
phase_1_dh_group string rw for VPNs, ro for Skytap on Azure ExpressRoute connections Phase 1 Diffie-Hellman Group
One of modp1536 or modp2048.

Visible only to administrators.
phase_1_encryption_algorithm string rw for VPNs, ro for Skytap on Azure ExpressRoute connections Phase 1 encryption algorithm. One of aes 256 or aes.

Visible only to administrators.
phase_1_hash_algorithm string rw for VPNs, ro for Skytap on Azure ExpressRoute connections Phase 1 hash algorithm. One of sha1 or sha256.

Visible only to administrators
phase_1_pre_shared_key string wo for VPNs, N/A for Skytap on Azure ExpressRoute connections Phase 1 pre-shared key.

Visible only to administrators.
phase_1_sa_lifetime integer rw for VPNs, ro for Skytap on Azure ExpressRoute connections Value in seconds of Phase 1 SA lifetime. Valid range: 1 to 2147483647.

Visible only to administrators.
phase_2_authentication_algorithm** string rw for VPNs, ro for Skytap on Azure ExpressRoute connections Phase 2 authentication algorithm. One of hmac_sha1, or hmac_sha256.

Visible only to administrators.
phase_2_encryption_algorithm string rw for VPNs, ro for Skytap on Azure ExpressRoute connections Phase 2 encryption algorithm. One of aes, aes 256, or aes_gcm.

Visible only to administrators.
phase_2_perfect_forward_secrecy Boolean rw for VPNs, ro for Skytap on Azure ExpressRoute connections If true, Perfect Forward Secrecy (PFS) is used.

Visible only to administrators.
phase_2_pfs_group string rw for VPNs, ro for Skytap on Azure ExpressRoute connections Shows name of PFS group if Phase 2 PFS is set to true.
One of modp1536 or modp2048.

Visible only to administrators.
phase_2_sa_lifetime integer rw for VPNs, ro for Skytap on Azure ExpressRoute connections Value (in seconds) of Phase 2 SA Lifetime. Valid range: 1 to 2147483647.

Visible only to administrators.
region string ro Skytap region (for example: US-West).

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

Visible only to administrators.
remote_peer_ip string rw for VPNs, ro for Skytap on Azure ExpressRoute connections Public IPv4 address associated with WAN endpoint on external network.

Visible only to administrators.
remote_subnets array ro List of remote subnets included or excluded from the WAN.
  • Included subnets are subnet ranges to which traffic from Skytap will be routed.
  • Excluded subnets are prevented from connecting to Skytap.

Remote subnets can only be added or removed via the WAN remote subnets sub-resource (https://cloud.skytap.com/vpns/<vpn-id>/subnets). For more information, see Include or Exclude Remote Subnet and Delete Included or Excluded Remote Subnet.

Field NameTypeDescription
cidr_blockstringThe IP address range of the subnet.
excludedBooleanIf set to false, this string specifies an included subnet; if set to true, it specifies an excluded subnet.
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).

The / character in the subnet ID and CIDR block will be escaped to %2F in URLs returned by the API.
route_based Boolean rw for VPNs, ro for Skytap on Azure ExpressRoute connections If true, the WAN is route-based.
If false, it’s policy-based.
sa_policy_level string rw for VPNs, ro for Skytap on Azure ExpressRoute connections Security policy level, the options are null, require, or unique.

Visible only to administrators.
status string ro Status of the VPN tunnel (inactive or active).
test_results collection ro Results of 4 tests: Connect, Phase1, Phase2, and Ping.

Visible only to administrators. Always null for Virtual Private Networks.
url string ro URI for the WAN.

Operations on WAN resources

List WANs

Request

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

Filter parameters

An optional region parameter can be used to filter the list of WANs by region. One of . For example, to see a list of WANs in US-West:

GET https://cloud.skytap.com/vpns?region=US-West

Response

Representation of WANs in the account.

Get WAN description

Request

GET https://cloud.skytap.com/vpns/{vpn-id}.json

You must be an administrator to make this request.

Response

Representation of specified WAN.

Create Skytap VPN

Request

When creating VPN, include all of the fields shown in the example below.

POST https://cloud.skytap.com/vpns.json

{
    "name": "VPN",
    "local_subnet": "10.0.0.1/24",
    "nat_local_subnet": false,
    "route_based": false,
    "local_peer_ip": "76.32.14.101",
    "remote_peer_ip": "74.2.147.3",
    "internet_key_exchange": "ikev2",
    "phase_1_encryption_algorithm": "aes 256",
    "phase_1_hash_algorithm": "sha256",
    "phase_1_pre_shared_key": "HelloWorld",
    "phase_1_sa_lifetime": 28800,
    "phase_1_dh_group": "modp1048",
    "phase_2_encryption_algorithm": "aes_gcm",
    "phase_2_authentication_algorithm": "hmac_sha256",
    "phase_2_perfect_forward_secrecy": true,
    "phase_2_pfs_group": null,
    "phase_2_sa_lifetime": 3600,
    "sa_policy_level": "require",
    "maximum_segment_size": null,
    "dpd_enabled": true
}

You must be an administrator to make this request.

Response

Representation of the new VPN.

Create Skytap-managed ExpressRoute

Request

When creating a Skytap-managed ExpressRoute, include all of the fields shown in the example below.

POST https://cloud.skytap.com/vpns.json

{
    "name": "VPN",
    "local_subnet": "10.0.0.1/24",
    "nat_local_subnet": false,
    "local_peer_ip": "76.32.14.101",
    "connection_type": "express_route"
}

You must be an administrator to make this request.

Response

Representation of the new VPN.

Create customer-managed ExpressRoute

Request

When creating a customer-managed ExpressRoute, include all of the fields shown in the example below.

POST https://cloud.skytap.com/vpns.json

{
    "name": "VPN",
    "local_subnet": "10.0.0.1/24",
    "nat_local_subnet": false,
    "local_peer_ip": "76.32.14.101",
    "connection_type": "express_route",
    "service_key": "abc-123"
}

You must be an administrator to make this request.

Response

Representation of the new VPN.

Test a VPN

Request

  1. Send a POST request to the WAN test subresource.

    POST https://cloud.skytap.com/vpns/{vpn-id}/test.json

     {
     "address": "10.0.0.1",
     "port": "443"
 }

Required and optional parameters

Required parameters
address An IP address from a machine that is running on the remote network and can respond to pings. The ping test will use the IP address to check the connection between Skytap and machines on your VPN.
Optional parameters
port A remote port that is open on the remote machine; if you don’t enter a port, no TCP connectivity test is performed.

Notes

  • You must be an administrator to make this request.
  • You can't test Skytap on Azure ExpressRoute connections from the API.

2. Retrieve the test results with a GET request to the VPN resource or the VPN test.

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

or

GET https://cloud.skytap.com/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/vpns/{vpn-id}.json

{
    "enabled": true
}

Notes

  • You must be an administrator to make this request.
  • You can't test Skytap on Azure ExpressRoute connections from the API.
Response

Updated VPN resource.

Edit the WAN

Request

PUT https://cloud.skytap.com/vpns/{vpn-id}.json

Notes

  • You must be an administrator to make this request.
    • name is the only field that can be edited on a Private Network Connection.</li></ul></div>
Response

Updated VPN resource.

Include remote subnet

Request

POST https://cloud.skytap.com/vpns/{vpn-id}/subnets.json

{
    "cidr_block": "10.0.0.0/24"
}

Notes

  • You must be an administrator to make this request.
  • You can't edit the remote subnet for Skytap on Azure ExpressRoute connections from the API.
Response

Representation of specified remote subnet

Exclude remote subnet

Request

POST https://cloud.skytap.com/vpns/{vpn-id}/subnets.json

{
    "cidr_block": "10.0.0.0/24",
    "excluded": "true"
}

Notes

  • You must be an administrator to make this request.
  • You can't edit the remote subnet for Skytap on Azure ExpressRoute connections from the API.
Response

Representation of specified remote subnet

Delete included or excluded remote subnet

Request

DELETE https://cloud.skytap.com/vpns/{vpn-id}/subnets/{subnet-id}

Notes

  • You must be an administrator to make this request.
  • You can't edit the remote subnet for Skytap on Azure ExpressRoute connections from the API.
Response

Deleted remote subnet

Attach/connect/disconnect/detach a virtual network to a WAN

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

Delete VPN

Request

DELETE https://cloud.skytap.com/vpns/{vpn-id}

Notes

  • You must be an administrator to make this request.
  • You can't delete Skytap on Azure ExpressRoute connections from the API.
Response

Deleted VPN.

Webhooks resource

Webhooks provide real-time streaming data that can be sent to a URL that you choose.

Webhooks reference URI

https://cloud.skytap.com/admin/webhooks.json

Webhooks resource model

The following fields are defined:

Field Name Type Access Description
category string ro Type of webhook. Allowed values are auditing and usage.
certificate string rw Public key of the TLS certificate.
created_at timestamp ro Date and time the webhook was created.
enabled boolean rw If true, the webhook is on.
id integer rw Webhook identifier.
updated_at timestamp ro Date and time the webhook was last edited.
url string rw URL of the webhook data endpoint.

Operations on webhooks

Get webhook

Request

GET https://cloud.skytap.com/admin/webhooks/{webhook-id}

Response
{
    "id": 456,
    "enabled": true,
    "url": "http://example.com/webhook",
    "certificate": "TLS-Public-Key",
    "category": "audit"
}

Create webhook

Request

POST https://cloud.skytap.com/admin/webhooks.json

{
    "url": "http://example.com/webhook",
    "category": "audit",
    "certificate": "TLS-Public-Key",
    "enabled": "true"
}
Required parameters
url URL of the webhook data endpoint.
category Type of webhook. Allowed values are audit and usage.
Optional parameters
certificate Public key of the TLS certificate for the webhook data endpoint (recommended).
Response

Representation of the webhook.

{
    "id": "13",
    "url": "https://test.net/",
    "certificate": "TLS-Public-Key",
    "category": "audit",
    "enabled": true
}

Required and optional parameters

Edit webhook

Request

PUT https://cloud.skytap.com/admin/webhooks/{webhook-id}

{
    "url": "https://example.com/webhook",
    "certificate": "New-TLS-Public-Key"
}
Response

Updated representation of the webhook.

{
    "id": "13",
    "url": "https://example.com/webhook",
    "certificate": "New-TLS-Public-Key",
    "category": "audit",
    "enabled": true
}

Change log

January 2024

June 2023

June 2022

  • REST API changes:
    • Added support for Power VM guestOS and guestOS_version.

February 2022

  • REST API changes:
    • SmartRDP is discontinued..

October 2020

  • REST API changes:
    • Added provider and provider_parameters to VM Imports to support VM imports from IBM Cloud Object Storage and Microsoft Azure Blob Storage VM imports resource.

February 2020

September 2019

June 2019

March 2019

  • REST API changes:
    • Added multiple-monitor attributes to the VM Hardware resource. This enables a new multiple-monitor display mode for the SRA browser client.

January 2019

September 2018

  • REST API changes: * Added a rate_limited Boolean to the Environment VMs resource. If a VM is being rate-limited because of high amounts of activity in the account, rate_limited will be true.

August 2018

July 2018

  • REST API changes:
  • Documentation improvements:
    • Changed API navigation buttons to match Skytap UI styles.
    • Corrected variable formatting in API requests.

June 2018

  • REST API changes:
    • Added shutdown_at_time and shutdown_on_idle attributes to Environments resource resource model. Added supported operations for enabling and disabling automatic shutdown for environments.
  • Documentation improvements:
    • Corrected documentation bug in the Environments resource model. The error field was incorrectly listed as errors.
    • Edited the sample requests for enabling automatic 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 two suspend options (suspend_on_idle and suspend_at_time), the other option is automatically nullified by the REST API; it doesn’t need to modified by the REST API user. This update corrected a documentation error; no REST API functionality changed for these operations.
    • Corrected the sample request for disabling automatic 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.

May 2018 (revision 1.55)

April 2018 (revision 1.54)

  • 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 (revision 1.53)

  • Updated the documentation for inclusion of Private Network Connections:

    • Renamed ‘VPNs’ resource to ‘WANs’ resource in the API documentation. The WANs resource now includes representations of VPNs and Private Network Connections. For backward-compatibility, the reference URI hasn’t changed. VPNs and Private Network Connections can both be accessed from:

      https://cloud.skytap.com/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 attribute to Environments resource resource model.
  • Split documentation for “Enable/Disable auto-suspend” operation into three sections:

October 2017 (revision 1.52)

  • 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 cumulative_svms_power usage limit types to user and account limits. The cumulative_svms_power usage limit can’t be edited.
    • Added notes that some VM hardware attributes can’t be edited and aren’t applicable to Power VMs, including vnc_keymap, uuid, rtc_start_time, time_sync_enabled, copy_paste_enabled, and nested_virtualization.
    • Added notes that some VM network adapter attributes can’t be edited for Power VMs, including mac, nic_type, and promiscuous_mode_enabled.
    • Added read-only architecture attribute to VM resource model; this is either power or x86.
    • Added includes_power attribute that can be optionally included during POST requests to the Imports resource.
    • Added svms_power option to resource_type in Usage reports.
    • Added ConcurrentPowerVMNotificationRule option to rule_type in Notifications resource.
    • Noted throughout that Power VMs can’t be suspended. In most cases, operations that would suspend a Power VM fail (for example: copying a environment with running Power VMs or creating a template from an environment that contains running Power VMs). However, there is one case where the operation succeeds: if you change an entire environment’s runstate to suspended, the x86 VMs are suspended and the Power VMs are skipped (they remain running)>. Refer to the documentation for a specific operation for more information about the expected behavior.

    • NOTE: Skytap has edited the error messages associated with user, department, and account limits. If an SVM or SVM hours limit is reached, the system now provides more details about which type of SVM limit was reached.

      • “SVMs limit” is now either “x86 SVMs limit” or “Power SVMs limit”. >* “SVM hours limit” is now either “x86 SVM hours limit” or “Power SVM hours limit”.

August 2017 (revision 1.51)

  • Updated representation of Network Adapters resource to describe new dynamic public IPs operations.
  • Updated Network Adapters resource resource model to include new descriptions of the public_ips and public_ips_counts fields. Added new public_ip_attachments array to there resource model.
  • Added classrooms_access field to Users resource (see Users resource). This attribute is used to indicate whether a user has access to create courses and schedule classes with the Classrooms extension.

  • Corrected documentation errors in the description of the request body for copying an environment or template between regions:

    • resource_mapping was incorrectly documented as an array. It is an object.
    • configuration_id was incorrectly described as configuration-id.

March 2017 (revision 1.50)

  • 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 (revision 1.49)

  • 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 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 (see Auditing reports resource).

December 2016 (revision 1.48)

  • Added previously undocumented parameter to Create environment operation (see Environments resource). When creating an environment, you can optionally specify a project to add the new environment to.

November 2016 (revision 1.47)

  • Fixed documentation error in the User resource. The account roles were incorrectly listed with spaces instead of underscores. The valid account roles are restricted_user, standard_user, user_manager, and admin.

July 2016 (revision 1.46)

  • Removed list of limited tag_types in VM labels resource. All multi value label categories can now be used as tag_types.

June 2016 (revision 1.45)

April 2016 (revision 1.44)

  • Corrected documentation error in description of can_import and can_export parameters in the User resource. These Booleans are true and false, not 0 and 1.
  • Added has_public_library parameter to the User resource.
  • 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 description of environment publish sets resource to match new UI. API element and field names haven’t changed.
  • Made anonymous_smart_rdp a read/write parameter in the environment publish sets resource. Previously, this had been write only.
  • Added optional sort parameters for viewing a list of schedules. See Schedules resource.
  • Added sample representation of vpn_attachments array in the Environment networks resource.

March 2016 (revision 1.43)

  • Deprecated use as an option for a VPN’s SA policy level. See VPN resource.
  • Corrected documentation error in sample request for adding a disk to a VM. Disk size must be included in an array. See VM resource.
  • Added platform_errors array to the Environment resource.

  • Edited Account Limit (Company Quota) resource to support regional limits:

    • Added region parameter to each limit.
    • Added option to filter list of limits by region.
    • Changed the response body data structure for customers with regional limits. If you have regional limits enabled in your account, each customer limit is now grouped into one of several arrays. For example, all global usage limits are included in a global array, while all limits for US-West are grouped in a US-West array. This change doesn’t affect customers who don’t have regional limits enabled.
  • Added rtc_start_time parameter to VM hardware element. This is used to set the VM BIOS clock at boot time. See VM resource.

February 2016 (revision 1.42)

December 2015 (revision 1.41)

November 2015 (revision 1.40)

The November 2015 release contains the following changes:

October 2015 (revision 1.39)

The October 2015 release contains the following changes:

  • Added reassign_context parameter to instructions on changing an environment or template’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 Environment resource.
  • Added instructions for running, stopping, or suspending multiple VMs within an environment (see Environment resource).
  • Added instructions for deleting multiple templates (see Template resource).
  • Expanded instructions for adding VMs to an environment. VMs can now be added from another environment (see Environment 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 resource.

September 2015 (revision 1.38)

The September 2015 release contains the following changes:

August 2015 (revision 1.37)

The August 2015 release contains the following documentation changes:

  • Documented operations for adding and deleting VM labels in the VM resource.
  • Documented promiscuous mode user permission in the User resource.
  • Documented promiscuous mode permission in the Network Interface resource.
  • Clarified that user name is still required with an API token. Added instructions for checking whether an API token is required.
  • Documented adding a network in the Network resource.
  • Documented adding select VMs from a template to an environment in the Environment resource.

July 2015 (revision 1.36)

The July 2015 release contains the following API changes:

  • Significant updates to the Import 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.

The July 2015 release contains the following documentation changes:

  • 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 resource.
  • Documented operations for removing data from the VM and environment user_data fields (see VM resource and Environment resource).
  • Added sections on enabling and disabling auto-suspend for an environment (see Environment resource).
  • Changed name of section about adding VMs to an environment. This was previously titled “Merge Template into Environment”; it’s now “Adding VMs to Environment.”
  • Added sections on deleting multiple VMs and environments (see VM resource and Environment resource).
  • Added query filters to the Schedules resource that can show a list of schedules that include a specific environment or template.

June 2015 (revision 1.35)

The June 2015 release contains the following documentation changes:

  • Added sort options for viewing a list of departments.
  • Added filter options for viewing a list of schedules.
  • Changed “reset” runstate value to “restarted.”

  • Moved the documentation for several resources into the documentation for the main resource:

May 2015 (revision 1.34)

The 1.34 release contains the following API changes:

  • Added subnet field to Network resource. This field allows you to define the network’s subnet address and size in a single field (e.g., 10.0.0.0/24). The previous subnet_addr and subnet_size fields will still be supported.
  • Added instructions for editing and deleting VM credentials
  • Adding instructions for adding, editing, and deleting VM notes.
  • Added Department resource, including operations for viewing and editing department limits.
  • Added instructions for adding, editing, and deleting environment notes.
  • Added supports_multicore and cpus_per_socket to the VM hardware element to enable multi-core CPU support.

The 1.34 release contains the following documentation changes:

April 2015 (revision 1.33)

The 1.33 release contains the following API changes:

The 1.33 release contains the following documentation changes:

Revision 1.32

The 1.32 release contains the following documentation changes:

Revision 1.31

The 1.31 release contains the following documentation changes:

  • Edited description of response for List Configuration under Environment resource.
  • Added note explaining how to compile a full list of configurations in the account.

Revision 1.30

The 1.30 release contains the following documentation changes:

  • Added the vpn_attachments field to the Network resource. This is a representation of the VPN Attachment resource. Added operation for attaching a VPN to a network.
  • Corrected the name of the “network_attachments” field in the VPN resource; this was incorrectly listed as “attached_networks.” Edited the description; this is also a representation of the VPN Attachments resource.
  • Renamed the “Attached Networks” resource to “VPN Attachment” resource. Removed unsupported fields and added operations that can be performed.
  • Removed the Resource Semantics sections. Full field descriptions are now in the tables that accompany each resource description.
  • Documented the Credentials element in the VM resource.
  • Edited the description of the suspend_on_idle field in the Configuration resource; included information about how to disable auto-suspend.

The 1.30 release contains the following API changes:

  • Our API now includes an optional “?keep_idle=true” parameter you can add to select API GET requests. This value will tell the auto-suspend timer to ignore the API request when determining whether the environment is still in use. The “?keep_idle=true” parameter can be added to the following requests:

    • GET https://cloud.skytap.com/configurations/<config-id>

    • GET https://cloud.skytap.com/vms/<publish set id>/desktop

      or

      GET https://cloud.skytap.com/vms/<publish set id>/desktops

      Without this parameter, API GET requests on a VM or environment will be recognized as activity in the environment and will delay auto-suspend from taking effect.

Revision 1.29

The 1.29 release contains the following documentation changes:

  • Edited notes stating that three fields will be returned when a list of templates, configurations, or users is requested; while full representation of each list item is still not returned for a list request, more than three fields will be displayed for each item.

The 1.29 release contains the following API changes:

  • Added anonymous_smart_rdp field to the Published Set resource. This field enables SmartRDP files to be downloaded through Published URLs.
  • Added Customer Quota resource.

Revision 1.28

The 1.28 release contains the following documentation changes:

  • Added methods for creating a network interface, connecting a network interface to a network, and disconnecting a network interface from a network.
  • Clarified that network interfaces can be modified on VMs in a configuration. You can’t modify these resources for VMs in a template.
  • Added method for changing a keyboard’s language settings on a VM. Documented vnc_keymap field under the VM resource Hardware element.
  • Changed the name of the “restarted” pseudo-state to “reset” throughout the documentation.

The 1.28 release contains the following functional changes:

  • Added the “nested_virtualization” and “copy_paste_enabled” fields under the VM resource Hardware element.
  • Added an /account/api_token request to the Security section; this allows users to find their current API security token.

Revision 1.27

The 1.27 release contains the following functional changes:

  • Added “Stage” and “Staged Execution” resources to support VM sequencing.
  • Added new “restarted” pseudo-state. This is documented in the Configuration Semantics section and can be used to restart both VMs and configurations.
  • Added possible transition for VMs in a “suspended” runstate; these can be moved from “suspended” to “halted”, which will result in a forced shutdown of the VM.

Revision 1.26

The 1.26 release contains the following documentation changes:

  • Changed maximum CPUs to 12 per VM in the US-East and US-West regions.
  • Changed maximum RAM to 131,072 per VM in the US-East and US-West regions.

Revision 1.25

The 1.25 release contains the following documentation changes:

  • Corrected “public” field name in Template resource; this was incorrectly listed as “public type”.

Revision 1.24

The 1.24 release contains the following documentation changes:

  • Moved API to help.skytap.com site.
  • Noted that once the runtime limit is met, VMs are set to “don’t publish.”

Revision 1.23

The 1.23 release contains the following functional changes:

  • Selected customers can now copy configurations and templates across regions, and this feature will be rolling out to all customers shortly. In preparation for this, these operations are documented in the “Operations” portion of the Templates and Configurations resource sections.
  • The “Department” and “Department Collection” resources have been added.
  • The “enable_time_sync” field has been added to the VM resource.

Revision 1.22

The 1.22 release contains the following documentation changes:

  • Added the “Automation Best Practices” section to provide best practices for writing API scripts.

Revision 1.21

The 1.21 release contains the following functional changes:

  • Added three fields to Published Sets resource: “runtime_limit,” “expiration_time” and “expiration_time_tz.” These will enable you to set runtime limits and expiration dates for published sets.

Revision 1.20

The 1.20 release contains the following documentation changes:

  • Documented “Acquire” and “Release” commands for the Public IPs resource
  • Documented the “Groups” resource
  • Added additional examples for creating Schedules
  • Revised some example commands to provide more accurate instructions

Revision 1.19

The 1.19 release contains the following documentation changes:

  • “Interfaces” section updated with additional field “icmp”
  • “region_backend” field documented for Configurations, Imports, Templates, and VMs
  • “instance_type” field documented on VMs
  • Minor fixes and style changes

Revision 1.18

The 1.18 release contains the following functional changes:

  • Project resource added to API; users can now view, edit, create and delete projects in the API

The 1.18 release contains the following documentation changes:

  • Project resource section added to documentation

Revision 1.17

The 1.17 release contains the following functional changes:

  • VM resource updated with “configuration_url” and “template_url” elements
  • “user_data” element added to Configuration, Template, and VM resources

Revision 1.16

The 1.16 release contains the following documentation changes:

  • The following resources have been renamed in the document to better reflect the actual name in the API:
    • The "Virtual Machine" resource is now the "VM" resource
    • The "Virtual Network" resource is now the "Network" resource
    • The "Virtual Network Interface" resource is now the "Network Interface" resource

The 1.16 release contains the following functional changes:

  • The “Copy Configuration” and “Copy Template” commands have been added, and are documented in the Configuration and Template resource sections.

Revision 1.15

The 1.15 release contains the following functional changes:

  • The API has been updated to include fields related to Network Address Translation in the following resources:
    • Virtual Network Interface
    • VPN

Revision 1.14

The 1.14 release includes the following documentation changes:

  • Added Appendix 2: Formatting of Dates, with information on how dates should be entered into the API.
  • Added “Usage Reports resource” section.

The 1.14 release includes the following functional changes:

  • The API now supports access to usage reports, as detailed in the “Usage Reports resource” section.

Revision 1.13

The 1.13 release includes the following documentation changes:

  • Public IP resource added to documentation

The 1.13 release includes the following functional changes:

  • Users can be enabled for SSO at account creation; this is documented in the User resource.

Revision 1.12

The 1.12 release includes the following documentation changes:

  • Added “regions” field to various elements

Revision 1.10

The 1.10 release includes the following documentation changes:

  • Added Schedule Collection section for details on viewing multiple schedules
  • Revised introduction for greater clarity
  • Documented support of JSON content type and covered relevant accept header and content type request.
  • Clarified attributes for the actions array in Schedules.
  • Added sample XML schedule to Schedules section.
  • Update to Templates resource with command for saving published sets as part of template.

The 1.10 release includes the following functional changes:

  • “can_import” and “can_export” added to user resource. These attributes determine if the user is able to import or export VMs.

Revision 1.9

The 1.9 release includes the following functional changes:

  • Addition of Schedules resource and operations for the resource
  • Addition of Executions resource and operations for the resource

Revision 1.8

The 1.8 release includes the following functional changes:

  • Addition of Import resource and operations for the resource
  • Addition of Export resource and operations for the resource

Revision 1.7

The 1.7 release includes the following functional changes:

  • Addition of Notification_Rule resource and operations for the resource
  • Remove ‘vnc_url’ field from Virtual Machine resource model. This field isn’t supported in the API.

Revision 1.6

The 1.6 release includes the following documentation changes:

  • Update to <configuration-ref> and <template-ref> XML tags used in the body of some PUT and POST operations. The correct tags are <configuration_id/> and <template_id/>. For these operations, id of templates and configuration should be used instead of the references.
  • Inter-Configuration Network Route (‘Tunnel’) resource and operations for the resource
  • Removed the requirement to have ‘lockversion’ on PUT operations on resources. ‘lockversion’ was originally envisioned to be a concurrency control mechanism. However, it resulted in an extra call users had to make for all PUT operations. We will consider other concurrency control mechanism for the API as we get more feedback on automation use cases.

Revision 1.5

The 1.5 release includes the following documentation changes:

  • We support 1 to 8 CPUs per VM.
  • Maximum RAM per VM is now 32,768 MB.
  • Described the use of security tokens with Basic Auth

Revision 1.4

The 1.4 release documents incompatible changes to the Quota resource object.

Revision 1.3 R4

The 1.3 R4 release includes the following documentation changes:

  • Deleting user requires transfer_user_id instead of transfer_user and it’s no longer optional

Revision 1.3 R3

The 1.3 R3 release includes the following documentation changes:

  • Introduced Skytap as product name.
  • Reformatted the documentation.

Revision 1.3 R2

The 1.3 R2 release includes the following documentation changes:

  • We support 1, 2, or 4 CPUs per VM.
  • Maximum RAM per VM is now 8192 MB.

Revision 1.3

The 1.3 release includes the following change:

  • Replacement of Anonymous Access resource with published set resource.

Revision 1.2 R2

The 1.2 R2 release includes the following documentation changes:

  • Creating a user requires email in addition to the login_name and password elements specified in R1.
  • R1 incorrectly specified that when creating a template the base configuration is specified through a config-ref instead of the correct configuration-ref element.
  • Corrected the units for storage usage limits.

Revision 1.2

The 1.2 release includes the following functional changes:

  • Addition of the anonymous_access element.

The 1.2 release included the following documentation changes:

  • Improved documentation of resource model fields, syntax, and semantics.
  • Documentation of the anonymous_access element.
  • Documentation of error code 423.

Revision 1.1

The 1.1 release includes the following functional changes:

  • Addition of the user and user quota elements.
  • Addition of the owner attribute for configuration and template objects.
  • Addition of the suspend_on_idle attribute for configuration objects.
  • Addition of the owner and public elements for asset objects.

The 1.1 release included the following documentation changes:

  • Expanded discussion of versioning and compatibility.
  • Expanded discussion of error status codes.
  • Documentation of the halted pseudo-state element for configuration and virtual machine objects.

  • Inclusion of the description element for template objects.

    • Type: The type of action that will be run. The following are legal actions: run, power off, save, suspend, shut down, create, delete.
    • Time: A string representing the time the action will take place. The format for the time is YYYY/MM/DD hh:mm, where YYYY is a four-digit year, MM is a two-digit month, DD is a two-digit day, hh is a two-digit hour and ss is a two-digit second. An example would be: “2012/07/28 11:09.”
    • Time_zone: A string representing the time zone of the execution. This should be the same as the schedule’s time zone.
    • user sorts usage by users;
    • group sorts usage by group, as well as the individual users within each group;
    • region groups the usage data by region;
    • raw will display the individual line items of raw usage data, allowing you to see every instance of both SVM or storage usage.

Copyright © 2024 Skytap, Inc. | Privacy Policy | Terms of Service | Support