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

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.
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 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"
    ]
}
Required parameter
  • configuration-id – ID of the environment being copied.
Optional parameters
  • 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.
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"
    ]
}
Required parameter
  • configuration_id – ID of the environment being copied.
  • target_region – Region where you want the new environment to be hosted. One of US-West, US-Virginia-M-1, US-Texas-M-1, US-East-2, US-Central, SG-Singapore-M-1, EMEA, DE-Frankfurt-1-1, CAN-Toronto, AU-Sydney-I-1, or APAC-2.
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.
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 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 does not 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.

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

or

{
    "merge_configuration": "12455",
    "vm_ids": [
        "888888",
        "222222"
    ]
}
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.
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 VM(s) 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

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

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 below, display_server must be set to rdp.This field can be edited when the VM is powered off.

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

display_server_port string rw Used to specify a custom port number for RDP or SSH connections in the SRA browser client.
This field can be edited when the VM is powered off.

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

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 VMs.
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 VMs.
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 empty until a VM is pinned. Accepted values are hard to pin a VM or empty to unpin it. Always null for x86 VMs.
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 VMs.
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 VMs.
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 VMs.
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 user data.

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 VMs is available only for SSH connections.

cpus integer rw Number of CPUs allocated to this virtual machine.
Valid range is 1 to 12. Maximum limit depends on the max_cpus setting.

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

cpw integer ro Estimated CPW (Commercial Processor Workload) for IBM i VMs.
cpus_per_socket integer rw for x86 VMs
ro for Power VMs

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


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

{"cpus": 8,"cpus_per_socket": 4}

Notes
  • The VM 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).
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.
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 cucle. 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_defaultBoolean`true` for licensed IBM i VMs.
ibmi_powerhaBoolean`true` if Power HA is enabled for this VM.
developer_licensesIntegerThe number of IBM Rational Developer for i licenses enabled for this VM.
instance_type string ro This field is not currently in use. It always returns as null.
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 for x86 VMs
ro for Power VMs
If true, nested virtualization is enabled on the VM. For more information, see Enabling nested virtualization.
Always false for Power VMs.
ram integer rw Amount of RAM allocated to this VM.
Valid range is 256 and 131,072 (MB). Maximum limit depends on max_ram setting

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

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 for x86 VMs
ro for Power VMs
Used to set the VM BIOS clock at boot. Must be a UNIX timestamp (for example, 1456168430 is the Unix timestamp for Feb 22, 2016 7:13 PM UTC) or null (to disable this feature).
You can’t set the rtc_start_time if time-sync is enabled
Always null for Power VMs.
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 VMs.
time_sync_enabled Boolean rw for x86 VMs
ro for Power VMs
If true, time-sync is enabled. For more information, see Editing VM hardware and guest OS settings.
Always false for Power VMs.
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 for x86 VMs
ro for Power VMs
User-defined, static Universal Unique Identifier (UUID). By default, this field is null; this means that Skytap automatically assigns the UUID. Maximum of 32 hexadecimal characters (0-9, A-F, a-f).
Always null for Power VMs.
upgradable Boolean ro If true, the VM is not on the latest supported hardware version; the VM hardware version can be upgraded through the Skytap UI
Always false for Power VMs.
vnc_keymap string rw for x86 VMs
ro for Power VMs
Keyboard language mapping. UTF-8 character type. For a list of supported international keyboards and attribute values, see Using an international keyboard with a VM. Attribute values are listed in parentheses on that page
Always null for Power VMs.

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

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

Starting Runstate New Runstate
Running Reset Stopped Halted Suspended
Running No change VM is powered off and then run Graceful shut down Forced shut down Suspended
Stopped Running VM (invalid) No change No change (invalid)
Suspended Running VM (invalid) (invalid) Forced shut down No change
  • Power VMs can’t be suspended.
  • Note that the reset and halted runstates 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"
}

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

Response

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

Download VM SmartRDP or RDP File

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

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

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

Cannot be performed on Power VMs.

Response

One of the following RDP files:

  • If the VM has a NAT IP address from a Skytap VPN, an RDP file that connects over :3389 will be returned
  • If the VM 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.
  • If the VM doesn’t have an RDP published service, a SmartRDP file will be returned.

Export a network endpoints report (.CSV)

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

Step 1: Create the report

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

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.

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

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

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

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 only appear on networks that are connected to a NAT-enabled network via ICNR or a VPN tunnel. It contains two arrays:
  • The vpn_nat_addresses array will provide the NAT IP and details about the associated VPN. Includes: ip_address, vpn_id, vpn_name, and vpn_url.
  • The network_nat_addresses array will provide the NAT IP address and details about the connected network. Includes: ip_address, network_id, network_name, network_url, configuration_id, and configuration_url.
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.

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

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.

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

This action isn’t supported for VMs in templates.

Response

Updated network adapter

Connect network adapter to network

Request

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

{
    "network_id": "123456"
}

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

This action isn’t supported for VMs in templates.

Response

Connected network adapter

Add/remove published services

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

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}

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
}

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/{X}

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

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

Response

Status

Secondary IPs resource

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

Secondary IPs reference URI

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

List secondary IPs

Request

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

Response

Representation of the secondary IPs

Add a secondary IP

Request

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

{
    "address": "10.0.2.2"
}

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

Response

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

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

Edit a secondary IP

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

Detach a secondary IP

Request

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

Where ip-id is the secondary IP’s ID.

Response

Removed secondary IP.

VM user data resource

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

VM user data reference URI

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

VM user data resource model

The following fields are defined:

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

Supported operations on VM user data

Get VM user data

Request

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

Response

Contents of user data field.

Update VM user data

Request

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

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

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

This action isn’t supported for VMs in templates.

Response

Updated user data field.

Remove contents of VM user data field

Request

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

{
    "contents": null
}

This action isn’t supported for VMs in templates.

Response

Updated user data field.

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.
prefer_local_routing Boolean rw If true, different subnets within an environment can communicate with each other.
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 parameters
  • name – Network name.
  • network_typeautomatic.
  • 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 Parameters
  • name – Network name
  • network_typemanual
  • 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

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

  • 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 user data resource

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

Environment user data reference URI

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

Environment user data resource model

The following fields are defined:

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

Operations on environment user data

Get environment user data

Request

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

Response

Representation of the user_data field.

Update environment user data

Request

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

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

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

Response

Updated representation of the user_data field.

Remove environment user data

Request

PUT https://cloud.skytap.com/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
anonymous_smart_rdp Boolean rw If true, the sharing portal includes the option to download a SmartRDP file. This file provides access to the environment while the sharing portal is active.
False by default.
custom_content string rw The content you want displayed in the custom content tab. The string can contain plain text or HTML. Limited to 32kb (approximately 32,000 characters).

This field is required if custom_content_enabled is true.

custom_content_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”)
<p class="info">expiration_date and expiration_date_tz must be entered as a pair.</p>
expiration_date_tz string rw (Optional) Time zone for the expiration date. For a list of time zones, see Time Zones and UTC Offsets.
<p class="info">expiration_date and expiration_date_tz must be entered as a pair.</p>
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 for accessing 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 ise empty.
  • If a password has been set, the API returns a string of 10 asterisks: **********

If ********** is sent as the value of the password element, it's ignored; the current password won't be changed.

publish_set_type string rw Type of sharing portal. Either (single_url or multiple_url):
  • single_url – Single sharing portal
  • multiple_url – Sharing portal set
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 VM(s) 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
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",
    "anonymous_smart_rdp": false,
    "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 Parameters
  • name – Sharing portal name.
Optional Parameters

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

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

Representation of the new sharing portal.

{
    "id": "22222",
    "name": "default",
    "url": "https://cloud.skytap.com/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,
    "anonymous_smart_rdp": false,
    "sso_required": false,
    "vms": [
        {
        "name": "Ubuntu Linux (64-bit)",
        "access": "use",
        "run_and_use": false,
        "vm_ref": "https://cloud.skytap.com/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,
    "anonymous_smart_rdp": false,
    "sso_required": false,
    "vms": [
        {
        "name": "Something else",
        "access": "use",
        "run_and_use": false,
        "vm_ref": "https://cloud.skytap.com/vms/12345",
        "error": false,
        "desktop_url": "https://cloud.skytap.com/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

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 only recognized for start up sequences. Delays are ignored during suspend, shut down, or power off sequences.

current_stage_index integer The index of this stage relative to the other stages in the configuration; 0 indicates the first stage, 1 indicates the second stage, 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 characters. UTF-8 character type. Will default 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 does not appear in the normal representation of a template; it must be called directly via a GET request to
https://cloud.skytap.com/templates/<template-id>/user_data.

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

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"
}
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.
{
    "configuration_id": "123456",
    "publish_sets": true,
    "vm_instance_multiselect": [
        "12345"
    ],
    "network_multiselect": [
        "11111"
    ]
}
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"
}
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"
}

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 wish 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”.

Required parameters
  • template_id – ID of the template you want to copy
  • target_region – Region where you want the new template to be hosted. US-West, US-Virginia-M-1, US-Texas-M-1, US-East-2, US-Central, SG-Singapore-M-1, EMEA, DE-Frankfurt-1-1, CAN-Toronto, AU-Sydney-I-1, or APAC-2
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

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

tag_type – One of several options listed in the resource table above. The tag_type from the request will be 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
  • 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 does not 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

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

integer

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

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

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

Description

sort

string

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

  • Sort by department name: name or name_desc
  • Sort by number of users: user_count or user_count_desc
  • Sort by date created: created_at_count or created_at_desc
  • Sort by date modified: updated_at or updated_at_desc
Response

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

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

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

activated

Boolean

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

last_login

string

Filters by user’s last login. Options:

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

query

string

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

Name Description
account_role Filters results to display users in a specific user role. Options: admin, user_manager, standard_user, or restricted_user.
group_id Filters results to display users in a specific group (for example, 1234).
project_id Filters results to display users in a particular project (for example, 1234). To filter by environments that aren’t in a project, use none.
Response

Representation of department users.

Add user(s) 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 user(s).

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

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

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

Remove user(s) from department

Request

DELETE https://cloud.skytap.com/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 does not delete the user(s).

Response

Empty response body

List department limits

Request

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

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

Response

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

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

Add, edit, or remove department limits

Request

By default, departments limits are set to null.

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

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

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

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

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

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

source_network_id – ID of the source network.

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

source_network_id and target_network_id 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:
    • User: An individual user (valid when scope is selected-users)
    • Group: A group of users defined in the account (valid when scope is selected-users)
    • Department: A department (valid when scope is selected-departments)
    • Region: A Skytap region (valid when scope is selected-regions-limit or selected-regions-quota)
  • id: If the resource type is a user, group, or department, id is a string representation of the identifier (for example: '1234') for the resource. If the resource type is a region, the id is the name of the region (for example: 'US-West').
  • name: The full name of the user, group, department, or region resource.

recipients

array

rw

This is an array of users and/or groups who will be notified when the rule is triggered.

The JSON representation of one element (recipient) of the array is given below:

{
    ...
    "recipients": [
        {
            "type": "MetaRecipient",
            "id": "1",
            "name": "Resource Consumer"
        }
    ],
    ...
}
  • type: Represents the type of recipient. The supported recipient types are:
    • User: An individual user
    • Group: A group of users defined in the account
    • MetaRecipient: A logical representation of a set of users in the account (for example, all Administrators)
  • id: If the recipient type is User or Group, this is the identifier for the user or group; if the recipient type is “MetaRecipient”, this field identifies the recipient, where:
    • 1: Resource Consumer
    • 2: All Admins
    • 3: All User Managers
    • 4: All Standard Users
  • name: If the recipient type is User or Group, this is the name of the user or group; if the recipient type is MetaRecipient, this field identifies one of four possible recipients
    • Resource Consumer: the consumer of the resource being monitored (e.g., owner of a VM)
    • All Admins: all Administrators in the account
    • All User Managers: all User Managers in the account
    • All Standard Users: all Standard Users in the account

ordinal

integer

ro

Used internally by Skytap. 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.
  • scope – See the options in the Notifications resource model above.
  • subjects – If scope is selected-users, selected-departments, or selected-regions, you must include the id and type of the subject(s) being monitored.
  • recipients – Include the id and type of the users who 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:

  • SVMHoursNotificationRule – Metered RAM hours usage against the user limit
  • StorageNotificationRule – Storage usage against the user limit
  • ConcurrentVMNotificationRule – Concurrent Metered RAM (x86) usage against the user limit
  • ConcurrentPowerVMNotificationRule – Concurrent Metered RAM (Power) usage against the user limit

    Available only if your account is enabled for Power VMs.

  • VMUptimeNotificationRule – VM running for more than N number of hours

threshold_amount

string

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

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

Response

Status and the new rule in the response body.

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

Delete user notification rule

Request

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

{
    "reassign_context": 1234
}

reassign_context – 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 adapter(s), 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

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

region – One of US-West, US-Central, US-East-2, EMEA, , DE-Frankfurt-I-1, CAN-Toronto, AU-Sydney-I-1, or APAC-2

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.

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 (i.e., the creation or deletion of environments). Each object has two attributes:
  • Type A string that is one of the legal action types: run, suspend, shut down, power off, and save.
  • Offset An integer equal to the number of seconds after start that this action will take place. For instance, if the action was scheduled to start 2 hours after the schedule was executed, the offset would be 7200.
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 &amp;amp; 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 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

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

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

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

template_id Lists schedules that contain a specific template; includes templates owned by other users in your customer account (for example: query=template_id:11111)

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

sort

string

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

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

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

  • 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&offset=20>; rel=”next”, </schedules?count=10&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": "suspend",
                "offset": "7200"
            }
        ],
    "start_at": "2013/09/09 09:00",
    "time_zone": "Pacific Time (US & Canada)"
}
Required parameters

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

Optional parameters

If you would like to assign actions to the schedule during the POST, include an actions array, with type and offset defined.

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

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

Response

Representation of the new schedule

Delete a schedule

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

Request

DELETE https://cloud.skytap.com/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:
  • `none` – No label data will be included in the report.
  • single: Single value labels will be included in the report.
  • all: Single and multiple value labels will be included in the report.

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

Operations on 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 would like to assign actions to the schedule during the POST, include an actions array, with type and offset defined.

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

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

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 Login name for the user.
password string wo The password field is write-only. A new password can be sent with this field, but it will always be returned as the special value ********** (10 asterisks).
If ********** is sent as the value of the password element, it’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 login.
ftp_url string ro Download location for VM image.
ftp_user_name string ro User name for FTP login.
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:
  • complete: When the export is complete, the status reads complete.
  • error: If an error occurs, the status reads error and the error details display in the errors field.
  • new: The status is new upon initial creation.
  • processing: The VM is being exported.
template_url string 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

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

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 depot, 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 depot 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 login. 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 login. 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.
provider string rw The source location from which VMs should be imported. Either FTP, IBM or AZURE. If no value is provided, FTP is assumed.
provider_parameters string rw Connection parameters for VM import source.
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.
AZURE
Field NameTypeAccessDescription
container_namestringrwThe Azure Blob Storage containter name.
connection_stringstringrwThe Azure Blod Storage connection string.
FTP
Field NameTypeAccessDescription
user_namestringroUser name for SFTP login.
passwordstringroPassword for SFTP login.
hostURIroSFTP host name.
urlURIroThe full SFTP path to the upload repo.
region string rw Region where the template will be stored. One of US-West, US-Virginia-M-1, US-Texas-M-1, US-East-2, US-Central, SG-Singapore-M-1, EMEA, DE-Frankfurt-1-1, CAN-Toronto, AU-Sydney-I-1, or APAC-2. 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

  • 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 parameters
  • template name – Name of the new environment
Optional parameters
  • region – Name of the region to upload to. If no region is specified, your default region (in your user settings) is used.
  • md5 – MD5 checksum. For more information about the valid formats, see Creating MD5 hash values for VM imports.
  • includes_power – Either true or false. Can be used only if Power VMs are enabled for your account. If true, Skytap 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 file(s) to the SFTP server.

Start the import

Request

After uploading the VM file(s) to the SFTP server, start the import with the following request:

PUT https://cloud.skytap.com/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 depot 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.
  • Private Network Connection: a Private Network Connection is a private, direct network connection between an external network and a Skytap data center.

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 Private Network Connections. For help with creating or editing a Private Network Connection, contact mailto:support@skytap.com
  • You must be an administrator to perform most actions on WAN resources.

Creating a VPN is a multi-step process:

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

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

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

WANs reference URI

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

Notes

  • Throughout the Skytap API, WANs are referred to as VPNs. Skytap has modified the VPNs resource to include both VPNs and Private Network 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 Private Network Connections.

Field Name Type Access Description
attached_network_count integer ro Number of networks attached to VPN or Private Network Connection.

Only visible to administrators.

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

Only visible to administrators.

connection_type string ro Type of WAN. Either vpn, express_route, or direct.
vpn is a Virtual Private Network; direct is a Private Network Connection.
dpd_enabled Boolean rw for VPNs, ro for PNCs If true, Dead Peer Detection is enabled.

Only visible to administrators.

enabled Boolean rw for VPNs, ro for PNCs If true, the VPN or Private Network Connection is enabled.
error string ro If there is an error, this field will contain information about the error. Otherwise, this field will be blank.

Only visible to administrators.

id string ro Identifier, in the form vpn-#.
internet_key_exchange string rw for VPNs, ro for PNCs Internet Key Exchange version associated with the VPN or Private Network Connection.
One of ikev1 or ikev2

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

name string rw User-defined name for the VPN or Private Network Connection. Limited to 255 characters. UTF-8 character type.
nat_local_subnet Boolean rw for VPNs, ro for PNCs If true, the VPN or Private Network Connection is NAT-enabled.
nat_pool_remaining integer ro Remaining assignable IP addresses for NAT.

Only appears if nat_local_subnet is true.

nat_pool_size integer ro Total size of IP address pool for NAT.

Only appears if nat_local_subnet is true.

network_attachments array ro Representations of the relationships between this VPN or Private Network Connection and any network(s) attached to it, including whether the network is currently connected. To view this array, make a GET request to GET https://cloud.skytap.com/vpns/&amp;lt;vpn-id&amp;gt;.
Related: Network Resource.

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

phase_2_pfs_group string rw for VPNs, ro for PNCs Shows name of PFS group if Phase 2 PFS is set to true.
One of modp1536 or modp2048.

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

remote_subnets array ro List of remote subnets included or excluded from the VPN or Private Network Connection.
  • Included subnets are subnet ranges to which traffic from Skytap will be routed.
  • Excluded subnets are prevented from connecting to Skytap.

Remote subnets can only be added or removed via the WAN remote subnets sub-resource (https://cloud.skytap.com/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 PNCs If true, the VPN or Private Network Connection is route-based.
If false, it’s policy-based.
sa_policy_level string rw for VPNs, ro for PNCs Security policy level, the options are null, require, or unique.

Only visible 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.

Only visible to administrators. Always null for Virtual Private Networks.

url string ro URI for the VPN or Private Network Connection.

Operations on WAN resources

List VPNs and Private Network Connections

Request

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

An optional region parameter can be used to filter the list of WANs by region. One of US-West, US-Central, US-East-2, EMEA, , DE-Frankfurt-I-1, CAN-Toronto, AU-Sydney-I-1, or APAC-2. For example, to see a list of WANs in US-West:

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

Response

Representation of VPNs and Private Network Connections in the account.

Get VPN or Private Network Connection description

Request

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

You must be an administrator to make this request.

Response

Representation of specified VPN or Private Network Connection.

Create VPN

Request

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

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

Notes

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

Representation of the new VPN.

Test a VPN

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

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

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

    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

    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 Private Network Connections from the API.</li></ul>
  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 Private Network Connections from the API.
Response

Updated VPN resource.

Edit the VPN or Private Network Connection

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

Deleted remote subnet

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

To attach, connect, disconnect, or detach a network to a VPN or Private Network Connection, edit the Networks resource. For instructions, see Network 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 Private Network 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"
}
Response

Representation of the webhook.

{
    "id": "13",
    "url": "https://test.net/",
    "certificate": "TLS-Public-Key",
    "category": "audit",
    "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).

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

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 does not need to modified by the REST API user. This update corrected a documentation error; no REST API functionality changed for these operations.
    • Corrected the sample 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 have not 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 does not 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.