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

Environments 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
id string ro Environment identifier.
url URI ro URI reference for the environment.
name string rw User-defined name of the environment. Limited to 255 characters. UTF-8 character type. Will default to source template’s name if null is provided.
error string ro Describes any errors with the environment.
platform_errors array ro Array containing information about select errors. Each object contains an incident_id parameter that can be used to troubleshoot issues with the Skytap support team.
runstate string rw Because it can potentially represent the states of many VMs, the ‘runstate’ of an environment is a synthesized value. The environment runstate results should be interpreted as follows:
  • stopped: all VMs are stopped
  • suspended: one or more VMs are suspended, others are stopped
  • running: one or more VMs are running

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

UTF-8 character type.

.
rate_limited Boolean ro If true, the environment is being rate-limited due to a high amount of activity in the account. For more information, see API best practice: Checking for busyness.
description string rw User-defined description of the environment. Limited to 1000 characters. Null allowed. UTF-8 character type.
owner URI rw URI reference of the environment’s owner (e.g., https://cloud.skytap.com/users/123456).
routable Boolean rw Indicates whether networks within the environment can route traffic to one another.
vms array rw Array of virtual machines in the environment. It is legal to have 0 entries in this array.
The API supports adding elements to the array indirectly by adding VMs to the environment; it also supports deleting entries from the array by a DELETE request on the array member.
networks array ro Array of networks in the environment. Every environment can have multiple networks; the number of total networks that can be created is restricted by your customer account’s network quota.

Networks are added to this list when they are connected to a network adapter on a VM in the environment. Similarly, networks are removed from this list when they are disconnected from network adapters on VMs in the environment. For more information, see Network Interface Resource

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.
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).
publish_sets array ro Array of published set resources providing anonymous access to VMs within the environment.
cidr_block integer ro Shows IP range that associated networks must be housed within.
suspend_on_idle integer rw The number of seconds an environment can be idle before it is automatically suspended.
If suspend_on_idle and suspend_at_time are both null, automatic suspend is disabled.
suspend_at_time timestamp rw The date and time that the environment will be automatically suspended.
If suspend_on_idle and suspend_at_time are both null, automatic suspend is disabled.
shutdown_on_idle integer rw The number of seconds an environment can be idle before it is automatically shut down.
If shutdown_on_idle and shutdown_at_time are both null, automatic shut down is disabled.
shutdown_at_time timestamp rw The date and time that the environment will be automatically shut down.
If shutdown_on_idle and shutdown_at_time are both null, automatic shut down is disabled.

Environments 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 will not be returned. To see a full representation of an environment, perform a GET request using the configuration ID (see Get Environment Description).

Get all environments

Request

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.

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 cannot 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"
    ]
}
  • 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-Central,US-East, US-East-2, EMEA, APAC, AUS-Sydney, or CAN-Toronto.
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 do not appear as starting states. These are pseudo-states:

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

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

Response

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

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

Notes

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

Change runstate of some VMs

Request

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

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

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

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

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 cannot 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 cannot be set to automatically suspend and shut down. Only one of the following settings can take effect: suspend_on_idle, suspend_at_time, shutdown_on_idle, or shutdown_at_time.
  • When you send a request that updates one of the four suspend or shutdown options, the other three options are automatically set to null by the REST API.
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 cannot be set to automatically suspend and shut down. Only one of the following settings can take effect: suspend_on_idle, suspend_at_time, shutdown_on_idle, or shutdown_at_time.
  • When you send a request that updates one of the four suspend or shutdown options, the other three options are automatically set to null by the REST API.
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 cannot be set to automatically suspend and shut down.. Only one of the following settings can take effect: suspend_on_idle, suspend_at_time, shutdown_on_idle, or shutdown_at_time.
  • When you send a request that updates one of the four suspend or shutdown options, the other three options are automatically set to null by the REST API.
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 cannot be set to automatically suspend and shut down.. Only one of the following settings can take effect: suspend_on_idle, suspend_at_time, shutdown_on_idle, or shutdown_at_time.
  • When you send a request that updates one of the four suspend or shutdown options, the other three options are automatically set to null by the REST API.
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 username and API token.
By default, the Vagrantfile contains <your username> and <your api token> placeholder values.
This parameter will be ignored if you do not 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 cannot 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 cannot 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 is 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 do not exist outside of environments or templates.
  • An environment or template can have multiple VMs.
  • Each VM is a unique resource. Therefore, a VM in a template will have a different ID than a VM in an environment created from that template.

Environment VMs reference URI

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

You can optionally specify the containing environment in the URL, but this is not 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
id string ro VM identifier.
name string rw User-defined name. Limited to 100 characters.

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

runstate string rw Runstate of VM. UTF-8 character type. See allowed values in parameters section of Change VM runstate below.
rate_limited boolean ro Shows if the VM is rate-limited.
hardware hardware rw Hardware description. For more information, see Notes on the “hardware” element.
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.
asset_id URI wo Used to mount an ISO on the VM. For instructions, see Mount ISO Asset.

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

hardware_version integer ro VM hardware version number. Always null for Power VMs.
interfaces interface[ ] ro Array of virtual network interfaces.
To edit this array, see VM network adapters.
notes array ro Array of notes stored on the VM. Includes text and id values.
To edit this array, see VM notes.
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.
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.
region_backend string ro Region that the resource is housed in (for example, US-West).
created_at timestamp ro Date and time the VM was created.
display_server string rw One of none, rdp, or ssh. Indicates whether an additional connection type is enabled in the Secure Remote Access (SRA) browser client. To use the audio_in and audio_out options below, display_server must be set to rdp.This field can be edited when the VM is powered off.

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

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

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

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

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

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

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

publish_set_refs publish_set_ref[ ] ro Array of references to published sets that include this VM. Contains details about the published sets and the anonymous URIs used to access them. Accessing these URIs does not require a Skytap account.

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

configuration_url or template_url string ro Location of VM. configuration_url is used for a VM in an environment. template_url is used for a VM in a template.
user_data string user_data does NOT appear in the normal representation of a VM; it must be requested from its own endpoint. See VM user data.

Notes on the “hardware” element

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

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

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

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

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


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

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

Notes
  • The VM cannot have more than 12 CPUs.
  • The number of CPUs must be evenly divisible by the number of cores per socket (for example, if you have 12 CPUs, the cores per socket must be 1, 2, 3, 4, or 6).
ram integer rw Amount of RAM allocated to this VM.
Valid range is 256 and 131,072 (MB). Maximum limit depends on max_ram setting

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

svms integer ro Number of SVMs used by this VM
guestOS string rw This field tells the underlying host which operating system the VM is running and whether nested hypervisors are enabled.
max_cpus integer ro Maximum settable CPUs for this VM.
min_ram integer ro Minimum settable RAM for this VM.
max_ram integer ro Maximum settable RAM for this VM.
vnc_keymap string rw for x86 VMs
ro for Power VMs
Keyboard language mapping. UTF-8 character type. For a list of supported international keyboards and attribute values, see Using an international keyboard with a VM. Attribute values are listed in parentheses on that page
Always null for Power VMs.
uuid integer rw for x86 VMs
ro for Power VMs
User-defined, static Universal Unique Identifier (UUID). By default, this field is null; this means that Skytap automatically assigns the UUID. Maximum of 32 hexadecimal characters (0-9, A-F, a-f).
Always null for Power VMs.
disks array rw Array of virtual disks within the VM. The disk size is in MiB; it will be converted to GiB in the Skytap UI. The maximum disk size is 2,096,128 MiB (1.999 TiB).
storage integer ro Total amount of storage consumed by the VM in MiB. Calculated by adding the storage size of all disks within the VM.
upgradable Boolean ro If true, the VM is not on the latest supported hardware version; the VM hardware version can be upgraded through the Skytap UI
Always false for Power VMs.
instance_type string ro This field is not currently in use. It always returns as null.
time_sync_enabled Boolean rw for x86 VMs
ro for Power VMs
If true, time-sync is enabled. For more information, see Editing VM hardware and guest OS settings.
Always false for Power VMs.
rtc_start_time Unix timestamp rw for x86 VMs
ro for Power VMs
Used to set the VM BIOS clock at boot. Must be a UNIX timestamp (for example, 1456168430 is the Unix timestamp for Feb 22, 2016 7:13 PM UTC) or null (to disable this feature).
You cannot set the rtc_start_time if time-sync is enabled
Always null for Power VMs.
copy_paste_enabled Boolean rw for x86 VMs
ro for Power VMs
If true, copy and paste is enabled between a local machine and the VM (when the VM desktop is accessed via the browser).
Always false for Power VMs.
nested_virtualization Boolean rw for x86 VMs
ro for Power VMs
If true, nested virtualization is enabled on the VM. For more information, see Enabling nested virtualization.
Always false for Power VMs.
architecture string ro Either power or x86.
rdp_port string ro Displays a port number, if the VM is configured to allow RDP connections in the SRA browser client over a custom port number.
ssh_port string ro Displays a port number, if the VM is configured to allow SSH connections in the SRA browser client over a custom port number.

Environment VM 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 MiB; it will be converted to GiB in the Skytap UI. The minimum disk size is 2048 MiB; the maximum is 2096128 MiB (1.999 TiB).
  • This request does not support URL query parameters. Use a request body to submit the data.
Response

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

{
    "id": "12345678",
    "name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
    "runstate": "busy",
    "hardware": {
        "cpus": 1,
        "supports_multicore": true,
        "cpus_per_socket": 1,
        "ram": 1024,
        "svms": 1,
        "guestOS": "ubuntu-64",
        "max_cpus": 12,
        "min_ram": 256,
        "max_ram": 262144,
        "vnc_keymap": null,
        "uuid": null,
        "disks": [
            {
                "id": "disk-5236169-10952835-scsi-0-0",
                "size": 20480,
                "type": "SCSI",
                "controller": "0",
                "lun": "0"
            }
        ],
        "storage": 20480,
        "upgradable": false,
        "instance_type": null,
        "time_sync_enabled": true,
        "rtc_start_time": null,
        "copy_paste_enabled": true,
        "nested_virtualization": false,
        "architecture": "x86"
    },
    "error": false,
    "asset_id": null,
    "hardware_version": 10,
    "max_hardware_version": 10,
    "interfaces": [
        {
            "id": "nic-1234567-1234567-0",
            "ip": "10.0.0.2",
            "hostname": "host-2",
            "mac": "00:50:56:14:34:E4",
            "services_count": 0,
            "services": [],
            "public_ips_count": 0,
            "public_ips": [],
            "vm_id": "12345678",
            "vm_name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
            "status": "busy",
            "network_id": "111111",
            "network_name": "Network 1",
            "network_url": "https://cloud.skytap.com/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 MiB; it is converted to GiB in the Skytap UI.
  • The minimum disk size is 2048 MiB (2 GiB), and the maximum disk size is 2096128 MiB (1.999 TiB).
  • You cannot make a disk smaller; you can make it larger.
  • This request does not support URL query parameters. Use a request body to submit the data.
Response

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

{
    "id": "12345678",
    "name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
    "runstate": "busy",
    "hardware": {
        "cpus": 1,
        "supports_multicore": true,
        "cpus_per_socket": 1,
        "ram": 1024,
        "svms": 1,
        "guestOS": "ubuntu-64",
        "max_cpus": 12,
        "min_ram": 256,
        "max_ram": 262144,
        "vnc_keymap": null,
        "uuid": null,
        "disks": [
            {
                "id": "disk-5236169-10952835-scsi-0-0",
                "size": 20480,
                "type": "SCSI",
                "controller": "0",
                "lun": "0"
            }
        ],
        "storage": 20480,
        "upgradable": false,
        "instance_type": null,
        "time_sync_enabled": true,
        "rtc_start_time": null,
        "copy_paste_enabled": true,
        "nested_virtualization": false,
        "architecture": "x86"
    },
    "error": false,
    "asset_id": null,
    "hardware_version": 10,
    "max_hardware_version": 10,
    "interfaces": [
        {
            "id": "nic-1234567-1234567-0",
            "ip": "10.0.0.2",
            "hostname": "host-2",
            "mac": "00:50:56:14:34:E4",
            "services_count": 0,
            "services": [],
            "public_ips_count": 0,
            "public_ips": [],
            "vm_id": "12345678",
            "vm_name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
            "status": "busy",
            "network_id": "111111",
            "network_name": "Network 1",
            "network_url": "https://cloud.skytap.com/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 does not support URL query parameters. Use a request body to submit the data.

Response

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

{
    "id": "12345678",
    "name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
    "runstate": "busy",
    "hardware": {
        "cpus": 1,
        "supports_multicore": true,
        "cpus_per_socket": 1,
        "ram": 1024,
        "svms": 1,
        "guestOS": "ubuntu-64",
        "max_cpus": 12,
        "min_ram": 256,
        "max_ram": 262144,
        "vnc_keymap": null,
        "uuid": null,
        "disks": [
            {
                "id": "disk-5236169-10952835-scsi-0-0",
                "size": 20480,
                "type": "SCSI",
                "controller": "0",
                "lun": "0"
            }
        ],
        "storage": 20480,
        "upgradable": false,
        "instance_type": null,
        "time_sync_enabled": true,
        "rtc_start_time": null,
        "copy_paste_enabled": true,
        "nested_virtualization": false,
        "architecture": "x86"
    },
    "error": false,
    "asset_id": null,
    "hardware_version": 10,
    "max_hardware_version": 10,
    "interfaces": [
        {
            "id": "nic-1234567-1234567-0",
            "ip": "10.0.0.2",
            "hostname": "host-2",
            "mac": "00:50:56:14:34:E4",
            "services_count": 0,
            "services": [],
            "public_ips_count": 0,
            "public_ips": [],
            "vm_id": "12345678",
            "vm_name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
            "status": "busy",
            "network_id": "111111",
            "network_name": "Network 1",
            "network_url": "https://cloud.skytap.com/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 do not 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 does not support it, you will receive an error message. Otherwise, you will be able run a VM from within the VM.

Change VM runstate

Request

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

{
    "runstate": "running"
}
Required parameters

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

Starting Runstate New Runstate
Running Reset Stopped Halted Suspended
Running No change VM is powered off and then run Graceful shut down Forced shut down Suspended
Stopped Running VM (invalid) No change No change (invalid)
Suspended Running VM (invalid) (invalid) Forced shut down No change
  • Power VMs can’t be suspended.
  • Note that the reset and halted runstates do not appear as starting states. These are pseudo-states:

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

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

Response

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

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

Mount ISO Asset

Request

PUT https://cloud.skytap.com/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 is not connected to a VPN, but it is configured for an RDP published service, an RDP file that connects over the published service port opening will be returned.
  • If the VM does not have an RDP published service, a SmartRDP file will be returned.

Export a network endpoints report (.CSV)

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

Step 1: Create the report

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

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

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/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 cannot 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 cannot 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.
type string ro Read-only representation of the tag_type field.
text string rw Contents of the label. Max 255 characters.

Supported operations on VM labels

Get VM labels

Request

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

Operations on VM notes

Get VM notes

Request

GET https://cloud.skytap.com/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
id string ro Identifier.
ip IP v4 address rw Internally, Skytap uses DHCP to provision an IP address (for example, 10.1.0.37) based on the MAC address. Skytap will not assign the same IP address to multiple interfaces on the same network. This field can be modified if you want to provide your own network information.
Each segment of the IP address must be within the valid range (0 to 255, inclusive).
hostname string rw Limited to 32 characters. Valid characters are lowercase letters, numbers, and hyphens. Cannot begin or end with hyphens. Cannot be gw.
mac string rw for x86 VMs
ro for Power VMs
Internally, Skytap provisions a MAC address for the network adapter (for example, 00:1e:c2:c3:52:61). Skytap will not assign the same MAC address to multiple interfaces. This field can be modified if you want to provide your own network information.
  • MAC addresses must begin with the hexadecimal digits 00:50:56.
  • The maximum value for a MAC address is 00:50:56:3F:FF:FF.
  • The valid MAC address range is 00:50:56:00:00:00 to 00:50:56:3F:FF:FF.
services_count integer ro Number of published services attached to the VM.
services service[ ] ro An array of a published services attached to the VM. To add a published service, see Published Service Resource.
public_ips_count integer ro If the VM is running:
  • The number of dynamic and static public IPs in use by the VM.
    If the VM is suspended or powered off:
  • The number of static public IPs attached to the VMs
public_ip_attachments public_ip_attachments[ ] ro An array of dynamic or static public IP objects attached to the network adapter. For dynamic IPs, these attachments appear even if the VM is suspended or shut down.
NameTypeDescription
idintegerUnique ID associated with the PIP attachment to this network adapter
public_ip_attachment_keyintegerUnique ID associated with the PIP attachment to this network adapter
addressstringFor dynamic public IPs:
  • If the public IP address is deployed, the IPv4 address attached to the VM.
  • null if the VM is not running.
For static public IPs:
  • The IPv4 public IP address attached to the VM.
connect_typeintegerEither static or dynamic.
hostnamestringFor dynamic PIPs, the VM hostname used in the FQDN.
For static PIPs, null.
dns_namestringFor dynamic PIPs, the entire fully-qualified domain name for the VM. For static PIPs, null.
public_ip_keystringUnique ID of the public IP address (if currently attached). Otherwise, null.
public_ips public_ip[ ] ro An array of a public IPs attached to the VM network adapter. If the VM is suspended or shut down, dynamic public IP addresses do not appear in this list.
nat_addresses object ro This object will only appear on networks that are connected to a NAT-enabled network via ICNR or a VPN tunnel. It contains two arrays:
  • The vpn_nat_addresses array will provide the NAT IP and details about the associated VPN. Includes: ip_address, vpn_id, vpn_name, and vpn_url.
  • The network_nat_addresses array will provide the NAT IP address and details about the connected network. Includes: ip_address, network_id, network_name, network_url, configuration_id, and configuration_url.
status string ro Runstate status of the VM that this network is attached to.
vm_id integer ro ID of the VM that this network is attached to.
vm_name string ro name of the VM that this network is attached to.
network_subnet string ro Subnet of network that this network adapter is attached to.
network_type string ro Type of network that this network adapter is attached to.
network_url URI ro URL for the network that this network adapter is attached to.
network_id integer rw ID of the network that this network adapter is attached to.
network_name string ro Name of the network that this network adapter is attached to.
nic_type string rw for x86 VMs
ro for Power VMs
Network adapter type. One of: default, e1000, pcnet32, vmxnet, vmxnet3, or e1000e. UTF-8 character type.
Always default for Power VMs.

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

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

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

Supported operations on 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 cannot be edited for Power VMs.
  • hostname – Hostname (can only be edited if the network adapter is connected to a network).
  • promiscuous – If true, promiscuous mode is enabled; promiscuous mode cannot be enabled for Power VMs.

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

This action isn’t supported for VMs in templates.

Response

Updated network adapter

Connect network adapter to network

Request

PUT https://cloud.skytap.com/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 cannot begin or end with a hyphen.
  • Max. of 32 characters.
Response

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

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

Detach dynamic public IP address and DNS name

Request

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

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
id string ro Identifier.
internal_port integer rw The port that is exposed on the interface. Typically this will be dictated by standard usage (e.g., port 80 for http traffic, port 22 for SSH).
external_ip IP address ro Exposed routable IP. Connections to this IP and port (below) are routed to the internal port in the guest VM. The external IP and port are selected by Skytap.
external_port integer ro Exposed routable port. The port number is selected by Skytap.

Operations on 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 cannot perform this action on VMs in templates.

Response

Representation of new published service.

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

Delete a published service

Request

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

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

You cannot perform this action on VMs in templates.

Response

Status

Secondary IPs 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 does not 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
id string ro Identifier
address IP address rw Secondary IP address assigned to the network adapter

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 is not available, an error will be returned.

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

Edit a secondary IP

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

Detach a secondary IP

Request

DELETE https://cloud.skytap.com/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 are not top-level elements of the API. Rather, they are elements properly contained within an environment. Operations on them are implicitly on the containing environment.

Environment networks 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
id integer ro Identifier.
url URI ro URI for the resource.
name string rw User defined name of the network. Limited to 255 characters. UTF-8 character type.
domain string rw Domain name for the Skytap network. Limited to 64 characters.
Valid characters are lowercase letters, numbers, and hyphens. Cannot be blank, must not begin or end with a period, and must start and end with a letter or number.
This field can be changed only when all virtual machines in the environment are stopped (not suspended or running).

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

subnet string rw Defines the subnet address and subnet mask size in CIDR format (for example, 10.0.0.0/24). IP addresses for the VMs are assigned from this subnet and standard network services (DNS resolution, CIFS share, routes to Internet) are defined appropriately for it.
The subnet mask size must be between 16 and 29. Valid characters are lowercase letters, numbers, and hyphens. Cannot be blank, must not begin or end with a period, and must start and end with a letter or number.

This field can be changed only when all virtual machines in the environment are stopped (not suspended or running).
The subnet field replaces the previous subnet_addr and subnet_size fields. The subnet_addr and subnet_size fields are still supported, if you would like to define the subnet address and subnet size separately.

gateway string rw Gateway IP address.
network_type string rw Type of network (must be automatic or manual)Once it is defined, this field cannot be edited.
tunnelable Boolean rw If true, this network can be connected to other networks.
tunnels array ro List of connections between this network and other networks.
primary_nameserver string rw User-provided primary name server for this network.
On an automatic network, Skytap provisions the domain name servers. Users can optionally override this and provide their own primary and secondary name servers. If this value is set, all name resolution requests are routed to this server.
Must be a valid IPv4 address.
secondary_nameserver string rw User-provided secondary name server for this network. The secondary_nameserver is used if the primary_nameserver does not resolve.
region string ro Region that the resource is housed in (for example, US-West).
nat_subnet string rw A CIDR block which determines the external IP addresses which will be assigned to network interfaces on connected networks. The larger the subnet, the larger the IP pool will be. Does not appear on manual networks or if an automatic network is not NAT-enabled.
Cannot overlap with subnet (see above).
Can be unset with "".
nat_pool_size integer ro The total number of IP addresses for external mapping. Does not appear if network is not NAT-enabled.
nat_pool_remaining integer ro Remaining assignable IP addresses for NAT. Does not appear if network is not NAT-enabled.
vpn_attachments array ro Representations of the relationships between this network and any VPN or Private Network Connections it is attached to, including whether the network is currently connected.

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

Operations on environment notes

Get environment notes

Request

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

expiration_date and expiration_date_tz must be entered as a pair.

start_time
end_time
time_zone
strings rw (Optional) Used to restrict the time of day the sharing portal can be accessed.
  • When defining an access window, start_time and end_time must be entered as a pair. When editing an existing access window, start_time and end_time can be edited separately.
  • The start and end times are expressed in HH:MM format.
  • To delete an access window, enter null for start_time and end_time.
  • You can optionally define the time_zone for the access window. If this is not defined, your personal time zone is used. For a list of time zones, see Time Zones and UTC Offsets.
multiple_url Boolean ro Indicates whether the publish_set_type is multiple_url.
password string wo If a password is included in this field, it is required for accessing the sharing portal. If you do not want to require a password for access, enter an empty string in this field.

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

  • If no password is set, the returned element will be empty.
  • If a password has been set, the API will return a string of 10 asterisks: **********

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

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

This field is required if custom_content_enabled is true.

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

This field is required if custom_content_enabled is true.

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

Operations on 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 is 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 will not take effect if this request is made within the auto-suspend window you have set (e.g., 5 minutes, 60 minutes, etc.). If you would like the auto-suspend timer to ignore this request and not treat it as activity, include ?keep_idle=true in the request.

Response

A representation of the desktop URL.

Edit sharing portal

Request

PUT https://cloud.skytap.com/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 are not top-level elements of the API. Rather, they are elements contained within an environment.

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

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

Environment VM sequencing stages 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 will not 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 do not want to run in the excluded_vms_ids array. You can optionally include the delay_after_finish_seconds and index fields.

An example is provided below:

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

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

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

Note that the excluded_vms_ids array will not be displayed. You can view the contents of this array by making a request to

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

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

If the request array does not contain all four stages, the API will return an error response and Skytap will not make any changes to the stages.

View a stage within the VM sequence

Request

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

Example response body:

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

A 404 error will return if the environment is not running, shutting down, suspending, or powering off.

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

Cancel a running VM sequence

Request

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

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

Response

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

If the VM sequence is not currently running, a 404 error will be returned.

Templates resource

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

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

Templates 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
id string ro Template identifier
url URI ro URI reference for template
name string rw User-defined name. Limited to 255 characters. UTF-8 character type. Will default to source environment’s name with - Copy added if null is provided.
busy Boolean ro Describes if the template is busy.

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

owner URI rw URI reference of the template’s owner (e.g., https://cloud.skytap.com/users/123456). This field is not displayed if the template is in the Skytap public library.
public Boolean ro Indicates whether the template is from the Skytap public library
description string rw User-defined description. Limited to 1000 characters. Null allowed. UTF-8character type.
vms vm[] ro Array of virtual machines in the template
networks network[] ro Array of networks in the template
region string ro Region that the resource is housed in (for example, US-West)
region_backend string ro Region that the resource is housed in (for example, US-West)
publish_sets array ro Array of sharing portals in the template
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.

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. * is not 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 do not 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 will not 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 are not saved.
  • vm_instance_multiselect – Array of one or more VM IDs to include in the template. If this parameter is not 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 is not 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 cannot 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 does not 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-Central,US-East, US-East-2, EMEA, APAC, AUS-Sydney, or CAN-Toronto
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 username and API token.
By default, the Vagrantfile contains <your username> and <your api token> placeholder values.
This parameter will be ignored if you do not 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 cannot 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 cannot 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 is 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 do not exist outside of environments or templates.
  • An environment or template can have multiple VMs.
  • Each VM is a unique resource. Therefore, a VM in a template will have a different ID than a VM in an environment created from that template.

Template VMs reference URI

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

You can optionally specify the containing template in the URL, but this is not 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 are not top-level elements of the API. Rather, they are elements properly contained within a template. Operations on them are implicitly on the containing template.

Template networks 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 cannot 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 is 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 are not 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 will not 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 SVMs, SVM hours, storage, concurrent VMs, public IPs, and networks across all of the users in your account.

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

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

Available only if your account is enabled for Power VMs.

concurrent_vmsintegerrwNumber of VMs that can be used at the same time.
concurrent_storage_sizeintegerrwMaximum storage limit for the account, units specified in MB.
cumulative_svmsintegerrwMaximum number of hours of cumulative SVM usage for x86 VMs.
cumulative_svms_powerintegerroMaximum number of hours of cumulative SVM 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.
region integer ro The name of the region that the limit applies to. If limit applies to the whole account, this parameter contains global.
usage integer ro The amount of resource in use or consumed (depending on the resource).
subscription integer ro The amount of resources you have budgeted for monthly usage; if you set the limit above the subscription, you can allow additional usage at an additional cost.
max_limit integer ro Max settable limit for the account; this is highest value that can be set for the quota. If max_limit is null, then the max limit is equal to the current limit.

Operations on 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": [
    {
      "id": "concurrent_svms",
      "quota_type": "concurrent_svms",
      "units": "integer",
      "limit": 10,
      "region": "US-East",
      "usage": 0,
      "subscription": 10,
      "max_limit": 10
    },
    {
      "id": "concurrent_storage_size",
      "quota_type": "concurrent_storage_size",
      "units": "MB",
      "limit": 51200,
      "region": "US-East",
      "usage": 10240,
      "subscription": 51200,
      "max_limit": 51200
    },
    {
      "id": "concurrent_networks",
      "quota_type": "concurrent_networks",
      "units": "integer",
      "limit": 10,
      "region": "US-East",
      "usage": 2
    },
    {
      "id": "concurrent_public_ips",
      "quota_type": "concurrent_public_ips",
      "units": "integer",
      "limit": 3,
      "region": "US-East",
      "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 quota that is read only or where the max settable limit “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 are editing a regional limit, you must include a region parameter. If you are editing a global limit, no region is required.
Response

The updated quota.

Assets resource

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

Assets cannot be created, modified, or deleted. You can only view assets and reference them.

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

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. * is not 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 do not 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 is not 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 is complete, append ?notify_by_email=1 to the URL.

Response
Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/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 within a period of time.

Notes

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

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 is not defined, the report will include all activities.

user

integer

rw

User ID number
If a user ID is not defined, the report will include all users.

department

integer

rw

Department ID number
If a department ID is not defined, the report will include activity by all departments.

project

integer

rw

Project ID number
If a project ID is not defined, the report will include all activity in all projects.

region

string

rw

Region name
If a region name is not 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 is not defined, the end date will be set to the current date and time.

environment_id

string

rw

If an environment or template ID is not 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 is 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

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

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

Operations on 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 are 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 are not 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 cannot 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 is 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
id integer ro Unique ID of group.
url string ro Link to group’s details page.
name string rw Descriptive name of the group.
description string rw Optional description of group.
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 is 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
id string ro Identifier.
status string ro Status of the tunnel.
source_network network rw Source network from where the connection was initiated. This network does not need to be “tunnelable” (visible to other networks).
target_network network rw Target network to which the connection was made. The network needs to be “tunnelable” (visible to other networks). To check the tunnelable attribute of this network, perform a GET request on the network resource (see Get Network Description).
error string ro Describes any errors with the ICNR connection.

Operations on 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 cannot be the same.

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

Response

Representation of the new tunnel.

{
    "id": "tunnel-123456-789012",
    "status": "not_busy",
    "error": null,
    "source_network": {
        "id": "111111",
        "url": "https://cloud.skytap.com/configurations/249424/networks/111111",
        "name": "Network 1",
        "network_type": "automatic",
        "subnet": "10.0.0.0/24",
        "subnet_addr": "10.0.0.0",
        "subnet_size": 24,
        "gateway": "10.0.0.254",
        "primary_nameserver": null,
        "secondary_nameserver": null,
        "region": "US-West",
        "domain": "skytap.example",
        "vpn_attachments": []
    },
    "target_network": {
        "id": "222222",
        "url": "https://cloud.skytap.com/configurations/808216/networks/222222",
        "name": "Network 2",
        "network_type": "automatic",
        "subnet": "10.0.2.0/24",
        "subnet_addr": "10.0.2.0",
        "subnet_size": 24,
        "gateway": "10.0.2.254",
        "primary_nameserver": null,
        "secondary_nameserver": null,
        "region": "US-West",
        "domain": "test.net",
        "vpn_attachments": []
    }
}

Delete a tunnel

Request

DELETE https://cloud.skytap.com/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 – SVM hours usage against account, department, or user limits (as defined in the scope)
  • StorageNotificationRule – Storage usage against account, department, or user limits (as defined in the scope)
  • ConcurrentVMNotificationRule – Concurrent x86 SVMs usage against account, department, or user limits (as defined in the scope)
  • ConcurrentPowerVMNotificationRule – Concurrent Power SVMs usage against account, department, or user limits (as defined in the scope)

    Available only if your account is enabled for Power VMs.

  • IPAddressesUsedNotificationRule – Public IP addresses usage against the account limit
  • NetworksUsedNotificationRule – Networks in use against the account limit
  • VMUptimeNotificationRule – VM running for more than N number of hours by all users or by select users (as defined in the scope)

threshold_amount

integer

rw

String defining the threshold level for the notification rule.

  • For VMUptimeNotificationRule rule, this value represents the number of hours.
  • For all other rules this value represents a percentage of limit or subscription.

scope

string

rw

A string that represents the scope at which events are being monitored. One of the following:

  • customer-quota – Monitor the global Subscription for the account
  • customer-limit – Monitor the global Limit for the account
  • all-users – Monitor all users
  • selected-users: Monitor selected users and/or groups of users
  • all-departments – Monitor all departments
  • selected-departments – Monitor selected departments
  • all-regions-quota – Monitor the regional Subscription for the account (for each enabled region)
  • all-regions-limit – Monitor the regional Limit for the account (for each enabled region)
  • selected-regions-quota – Monitor the regional Subscription for the account (for selected regions)
  • selected-regions-limit – Monitor the regional Limit for the account (for selected regions)

All scopes are not valid for every rule type. See the table below.

subjects

subjects[]

rw

When scope is selected-users, selected-departments, selected-regions-limit, or selected-regions-quota, this array represents the list of users (and/or groups), departments, or regions being monitored.

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

{  
    ...  
    "subjects": [
        {
            "type": "User",
            "id": "11",
            "name": "Joe User"
        }
    ],
    ...
}
  • type: Represents the type of subject. Supported subject types are:
    • User: An individual user (valid when scope is selected-users)
    • Group: A group of users defined in the account (valid when scope is selected-users)
    • Department: A department (valid when scope is selected-departments)
    • Region: A Skytap region (valid when scope is selected-regions-limit or selected-regions-quota)
  • id: If the resource type is a user, group, or department, id is a string representation of the identifier (for example: '1234') for the resource. If the resource type is a region, the id is the name of the region (for example: 'US-West').
  • name: The full name of the user, group, department, or region resource.

recipients

recipients[]

rw

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

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

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

ordinal

integer

ro

Used internally by Skytap. Do not write dependencies on this value.

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

Scroll the table to see all of the available options.

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

Additionally…

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

Operations on 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 are notified when the event occurs.

You must be an administrator to perform this action.

Response

Status and the new rule in the response body.

{
    "id": "123456",
    "threshold_amount": 50,
    "rule_type": "StorageNotificationRule",
    "scope": "selected-users",
    "ordinal": 123,
    "subjects": [
        {
            "type": "User",
            "id": 11,
            "name": "John Doe"
        }
    ],
    "recipients": [
        {
            "type": "MetaRecipient",
            "id": 2,
            "name": "All Admins"
        }
    ]
}

Delete account-wide notification rule

Request

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

You must be an administrator to perform this action.

Response

Status only

Notification rules resource (user-defined)

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

Notes

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

    Available only if your account is enabled for Power VMs.

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

threshold_amount

string

rw

String defining the threshold level for the notification rule.

  • For the VMUptimeNotificationRule rule type, this value represents the number of hours.
  • For all other rules this value represents a percentage of usage.

ordinal

integer

ro

Used internally by Skytap. Do not 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
id integer ro Identifier.
url URI ro URI reference for resource.
name string rw User-defined project name.
summary string rw User-defined description of project.
auto_add_role_name string rw If set to viewer, participant, editor, or manager, Skytap will assign the specified project role to every new user added to the project. The project role roles of existing project members will be unchanged. If auto-add is disabled, this field will be null.
show_project_members Boolean rw Determines whether projects members can view a list of other project members.

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
id string ro ID of the public IP address (same as address).
address string ro Unique IPv4 public IP address.
region string ro Region that the resource is housed in (for example, US-West).
nics array ro Representation of attached network adapter(s), if any. Includes network adapter id and deployed status.
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, US-East-2, EMEA, APAC, AUS-Sydney, or CAN-Toronto.

This request can only be made by administrators.

Response

Representation of newly-acquired public IP address.

Release static public IP address

Request

POST https://cloud.skytap.com/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
id string ro Unique identifier for schedule.
url string ro Full URL for schedule.
title string rw User-defined name of the schedule. Limited to 256 characters.
time_zone string rw The time zone in which the scheduled action will run. Entered as English strings, e.g. Mumbai or Pacific Time (US &amp;amp; Canada). For a list of time zones, see Time Zones and UTC Offsets.
start_at string rw A string specifying when the schedule will execute. The format for the time is YYYY/MM/DD hh:mm. For example: 2017/07/28 11:09.
Notes
  • In the above example, there is no UTC offset, as the time zone is determined by the time_zone string.
  • If a UTC offset is included (for example 2017/07/28 11:09 -0400), the UTC offset supersedes the time_zone setting.
end_at string rw This string specifies the end date of a schedule. The format for the time is YYYY/MM/DD hh:mm. This string is only relevant if the schedule is set to recur (see recurring_days) and/or is set to delete at the end of its operations (see delete_at_end, below).
Notes
  • If set to recur, the end_at time will specify the date at which the schedule stops recurring.
  • If delete_at_end is set to true, then the end_at date will determine the time that the schedule's environment is deleted.
  • If both recurrence and deletion are enabled, the schedule will both cease recurring and delete the environment at this time.
  • If a UTC offset is included (for example 2017/07/28 11:09 -0400), the UTC offset supersedes the time_zone setting.
delete_at_end Boolean rw If end_at is set, this Boolean determines whether the schedule’s environment is deleted when the time specified in end_at is reached.
notify_user Boolean rw Determines whether the schedule’s owner receives an email after the completion of a successful action. The user will always be notified when an action fails to complete, even if notify_user is not enabled.
executions executions [ ] ro Array of objects that collectively represent an action performed when the schedule runs.
The fields identify the resource targeted by the action, the action to be performed, and the time when the action will start.
Before a schedule has been run, the executions array will contain an empty list; once started, the array will detail the target of the next action and the action to be performed:
Field NameTypeDescription
idstringThe execution's ID
urlstringThe execution's reference URL
schedule_idstringID of the schedule execution belongs to
schedule_urlstringURL of same schedule
configuration_idstringID of environment that the executions affects
configuration_urlstringURL of environment that the executions affects
next_actionobjectA structure that details the target and scheduled time of the next action that will take place as part of the execution
user_idstringThis will display the ID of the execution's owner if that owner is an administrator; otherwise, it will be blank.
user_urlstringThis will display the URL of the execution's owner if that owner is an administrator; otherwise, it will be blank.
recurring_days recurring_days [ ] rw Array that lists the days on which the schedule will recur.
  • If this array is blank, the schedule will run until its final operation has been performed, and then delete itself.
  • By entering one or more days in this string (Sunday, Monday, etc.) the schedule will continue to exist and will recur on those dates until the time set in end_at.
actions actions [ ] rw Array of objects comprising all schedules actions in a schedule, with the exception of actions that cannot recur (i.e., the creation or deletion of environments). Each object has two attributes:
  • Type A string that is one of the legal action types: run, suspend, shut down, power off, and save.
  • Offset An integer equal to the number of seconds after start that this action will take place. For instance, if the action was scheduled to start 2 hours after the schedule was executed, the offset would be 7200.
next_action_name string ro The name of the next action that will execute as part of the schedule. This can be one of the legal actions (above), start (if the schedule has not yet executed), or delete (if all scheduled actions have completed, end_at has a value, and delete_at_end is set as true).
next_action_time string ro The time when the next action (specified in next_action_name, above) will occur. The format is YYYY/MM/DD hh:mm.
user object ro Key-value pairs representing the schedule’s owner. It contains the following fields:
  • id: the user's account name
  • url: the URL of the user's details page
  • login_name: the name used to sign in to Skytap
  • first_name: the user's first name
  • last_name: the user's last name
  • email: the email address registered with Skytap
region string ro Region that the resource is housed in (for example, US-West).

Environment fields

These fields only apply to schedules operating on environments.

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

Template fields

These fields only apply to schedules operating on templates.

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

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 are 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 is not necessary for JSON.

Response

Representation of the new schedule

Delete a schedule

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

Request

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

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
id integer ro ID of usage report.
utc Boolean rw If true, the report will use the UTC time zone.
If false, the report will use the admin’s local time zone. False is the default.
resource_type string rw Type of resource usage to report on.
One of storage , svms, or svms_power:
  • storage: Storage usage will be reported.
  • svms: Cumulative SVM usage and max concurrent SVM usage for x86 VMs will be reported. svms is the default.
  • svms_power: Cumulative SVM usage and max concurrent SVM usage for Power VMs will be reported.
region string rw Region to report usage on (for example, US-West). all is the default.
label_type string rw One of none , single, or all:
  • `none` – No label data will be included in the report.
  • single: Single value labels will be included in the report.
  • all: Single and multiple value labels will be included in the report.

Labels are only available for ungrouped reports. If label_type is single or all, group_by will automatically be set to raw.
group_by string rw How usage data is grouped.
One of user, group, region, department, or raw.
user is the default.
aggregate_by string rw Determines the increments in which data is displayed. One of month, day, or none. none displays activity as a lump sum in that period.
Reports grouped by raw must use none for aggregation.
results_format string rw File format of the report. One of csv or json.
ready Boolean ro If true, the report is ready for access.
url string ro URL where the report can be accessed.
notify_by_email Boolean rw If true, the report will be emailed to you when it is complete (CSV report only).
email string ro Email address the report will be sent to; this is the email address of the API user.
start_date
end_date
strings rw Start and end date for data collection period. Either YYYY/MM/dd HH:mm:ss format or ISO 8601 format (2013-03-21T01:00:00.000Z). If blank, the report will include usage from the current calendar month.
Usage data is available from the past two years. If the start_date or end_date is outside of this period, the report may include partial data or no data.
total_concurrent_overage string ro Number of on-demand SVM hours charged to the account.
high_level_above_subscription string ro Number of concurrent SVMS above the subscription at the highest point in the report period.
total_usage string ro Total number of SVM hours used by the account.
total_concurrent_overage string ro Number of on-demand SVM hours charged to the account.
start_level integer ro Number of concurrent SVMs in use at the beginning of the report period selected.
end_level integer ro Number of concurrent SVMs in use at the end of the report period selected.
high_level integer ro Maximum number of concurrent SVMs 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.
low_level integer ro Number of concurrent SVMs running at the lowest point in the report period.
low_date string ro Point in time at which the low_level value was achieved.
high_count integer ro Maximum number of VMs running at the highest point in the report period (peak).

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.

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

    (abridged response body):

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

Users resource

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

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

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  
id string ro Identifier.  
url URI ro URI reference for the user.  
login_name string rw Login name for the user.  
password string wo The password field is write-only. A new password can be sent with this field, but it will always be returned as the special value ********** (10 asterisks).
If ********** is sent as the value of the password element, it is ignored; the current password will not be changed.
 
first_name
last_name
strings rw First and last name strings used for display in the UI. Not validated for uniqueness.  
title string rw Optional text field for user title.  
email string rw Email address to which notifications may be sent. Not validated at submit time.  
created_at timestamp ro Date and time that the user account was created.  
activated Boolean ro Indicates whether the user has activated his or her account.  
default_region string rw Default region used for VM imports, asset uploads, new VPNs, and new public IP addresses.  
account_role string rw Defines the user’s access to features and settings. One of:
  • restricted_user
  • standard_user
  • user_manager
  • admin

For more information on user roles, see User Roles and Access Permissions.
 
quotas quotas[ ] 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.
 
configurations configurations[ ] ro Array of environments that the user owns.  
templates templates[ ] ro Array of templates that the user owns.  
assets assets[ ] 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.  
has_public_library Boolean rw for user accounts
ro for admin accounts
Determines if a user or administrator can access public templates and public assets owned by Skytap. By default, this value is true. Administrator accounts have this value locked to true.  
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.  
classrooms_access Boolean rw for user accounts
ro for admin accounts
Indicates whether the user has access to create courses and schedules classes with the Classrooms extension. Administrator accounts have this value locked to true.{::nomarkdown}<p class="info">This field is visible only if the Classrooms extension; otherwise, this field is hidden.</p> {:/}
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.  
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.  

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 will not 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 is not 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,
   "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 cannot be edited.
  • This request is to the User Quotas sub-resource, which is contained with the User resource.
Response

Representation of the new limit.

Edit user limit

Request

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

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

Operations on 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 are 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 file(s) to the Skytap SFTP depot. This is done outside of the API using an SFTP client. You will be given the SFTP depot’s hostname and access credentials in the response body for the request to create a new import job
  3. Start the Import
  4. Get the Import Status; you will also be notified via email when the import is complete

Imports 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
id string ro Reference ID for import job.
ftp_user_name string ro User name for SFTP login.
ftp_password string ro Password for SFTP login.
ftp_host string ro SFTP host name.
ftp_url string ro The full SFTP path to the upload repo: sftp://<sftp-username-ref><sftp-password-ref>@<hostname-ref>/upload/.
template_name string rw Name of environment to be created; required for all imports.
configuration_url string ro This field does not exist until the “status” field equals “complete.” At this point, this field will contain the URL for the new Skytap environment.
status string rw Can equal one of four states:
  • new: The import job has been created.
  • processing: To start the import process, change the status to processing.
  • error: If an error occurs, the status is error and the error will be detailed in the errors field (below).
  • complete: The import is complete.
errors string ro Describes general import error(s) (when status contains error). General import errors include mismatched MD5 checksums, unsupported file type, missing files, and import jobs that would exceed the user’s storage limit.
expiration_date timestamp ro Date import job will be deleted.
user string ro An array defining the user who created the import. Includes:
  • id
  • url
  • login_name
  • first_name
  • last_name
region string rw Region where the template will be stored. One of US-West, US-Central,US-East, US-East-2, EMEA, APAC, AUS-Sydney, or CAN-Toronto. Use the location closest to the majority of your users. If no region is specified, the import will default to US-West.
region_backend string rw Region that the resource is housed in (for example, US-West).
md5 string rw Optional field for user-provided MD5 checksum . ASCII character type. The format must one of the following:
  • MD5 (HW10.7z) = bca6d3862c661b615a374d7ef61252c5
  • 9f1001eb94538c5ca664e1e1740b3504 HW10.7z
  • 9f1001eb94538c5ca664e1e1740b3504 *HW10.7z (for binary transfers)
vms array ro Array of VMs in the import job. Includes:
  • error
  • errors (VM-level import errors, such as hardware version errors, prohibited characters in the file name, etc.)
  • id
  • is_finished
  • name

Operations on 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 are 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 Cloud checks that the region supports Power VMs; Skytap Cloud presents an error prior to processing the import if Power VMs are not supported in that region.
Response

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

Start the import

Request

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

PUT https://cloud.skytap.com/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 will not 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 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 or Private Network Connection’s ID number includes vpn-.

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  
id string ro Identifier, in the form vpn-#.  
name string rw User-defined name for the VPN or Private Network Connection. Limited to 255 characters. UTF-8 character type.  
url string ro URI for the VPN or Private Network Connection.  
status string ro Status of the VPN tunnel (inactive or active).  
enabled Boolean rw for VPNs, ro for PNCs If true, the VPN or Private Network Connection is enabled.  
remote_subnets array ro List of remote subnets included or excluded from the VPN or Private Network Connection.
  • Included subnets are subnet ranges to which traffic from Skytap will be routed.
  • Excluded subnets are prevented from connecting to Skytap.

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

Field NameTypeDescription
idstringThe identifier of the remote subnet (for example, 22.22.0.0/16)In API responses, the id will be prefaced by x if the subnet is excluded (for example, x22.22.0.0/16).
cidr_blockstringThe IP range of the subnet.
excludedBooleanIf set to false, this string specifies an included subnet; if set to true, it specifies an excluded subnet.

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

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

Only appears if nat_local_subnet is true.

 
nat_pool_remaining integer ro Remaining assignable IP addresses for NAT.

Only appears if nat_local_subnet is true.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

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

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

Only visible to administrators.

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

Only visible to administrators

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

The use SA policy level was deprecated in March 2016.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Only visible to administrators.

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

Operations on 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, EMEA, APAC, AUS-Sydney, or CAN-Toronto. 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",
    "phase_1_encryption_algorithm": "3des",
    "phase_1_hash_algorithm": "md5",
    "phase_1_pre_shared_key": "HelloWorld",
    "phase_1_sa_lifetime": 28800,
    "phase_1_dh_group": "modp1024",
    "phase_2_encryption_algorithm": "3des",
    "phase_2_authentication_algorithm": "hmac_md5",
    "phase_2_perfect_forward_secrecy": false,
    "phase_2_pfs_group": null,
    "phase_2_sa_lifetime": 3600,
    "sa_policy_level": "require",
    "maximum_segment_size": null,
    "dpd_enabled": true
}
Notes
  • You must be an administrator to make this request.
  • You cannot create Private Network Connections from the API.
Response

Representation of the new VPN.

Test a VPN

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

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

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

    An IP address from a machine that is running on the remote network and can respond to pings. The ping test will use the IP to check the connection between Skytap and machines on your VPN.

    Optional

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

    Notes
    • You must be an administrator to make this request.
    • You cannot test Private Network Connections from the API.
  2. Retrieve the test results with a GET request to the VPN resource or the VPN test.

     GET https://cloud.skytap.com/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 cannot test Private Network Connections from the API.
Response

Updated VPN resource.

Edit the VPN or Private Network Connection

Request

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

Notes
  • You must be an administrator to make this request.
  • name is the only field that can be edited on a Private Network Connection.
Response

Updated VPN resource.

Include remote subnet

Request

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

{
    "cidr_block": "10.0.0.0/24"
}
Notes
  • You must be an administrator to make this request.
  • You cannot edit the remote subnet for Private Network Connections from the API.
Response

Representation of specified remote subnet

Exclude remote subnet

Request

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

{
    "cidr_block": "10.0.0.0/24",
    "excluded": "true"
}
Notes
  • You must be an administrator to make this request.
  • You cannot edit the remote subnet for Private Network Connections from the API.
Response

Representation of specified remote subnet

Delete included or excluded remote subnet

Request

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

Notes
  • You must be an administrator to make this request.
  • You cannot edit the remote subnets for Private Network Connections from the API.
Response

Deleted remote subnet

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

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

Delete VPN

Request

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

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

Deleted VPN.

Change log

September 2018

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 has not 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 quota types to user and account limits. The cumulative_svms_power quota cannot be edited.
    • Added notes that some VM hardware attributes cannot be edited and are not applicable to Power VMs, including vnc_keymap, uuid, rtc_start_time, time_sync_enabled, copy_paste_enabled, and nested_virtualization.
    • Added notes that some VM network adapter attributes cannot be edited for Power VMs, including mac, nic_type, and promiscuous_mode_enabled.
    • Added read-only architecture attribute to VM resource model; this is either power or x86.
    • Added includes_power attribute that can be optionally included during POST requests to the Imports resource.
    • Added svms_power option to resource_type in Usage reports.
    • Added ConcurrentPowerVMNotificationRule option to rule_type in Notifications resource.
    • Noted throughout that Power VMs cannot be suspended. In most cases, operations that would suspend a Power VM fail (for example: copying a environment with running Power VMs or creating a template from an environment that contains running Power VMs). However, there is one case where the operation succeeds: if you change an entire environment’s runstate to suspended, the x86 VMs are suspended and the Power VMs are skipped (they remain running)>. Refer to the documentation for a specific operation for more information about the expected behavior.
    • NOTE: Skytap Cloud has edited the error messages associated with user, department, and account limits. If an SVM or SVM hours limit is reached, the system now provides more details about which type of SVM limit was reached.

      • “SVMs limit” is now either “x86 SVMs limit” or “Power SVMs limit”. >* “SVM hours limit” is now either “x86 SVM hours limit” or “Power SVM hours limit”.

August 2017 (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 will be now be grouped into one of several arrays. For example, all global quotas will be included in a global array, while all limits for US-West will be grouped in a US-West array. This change does not affect customers who do not have regional limits enabled.
  • Added rtc_start_time parameter to VM hardware element. This is used to set the VM BIOS clock at boot time. 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 username 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 is 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 cannot 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 NotificationRule resource and operations for the resource
  • Remove ‘vnc_url’ field from Virtual Machine resource model. This field is not 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 is no longer optional

Revision 1.3 R3

The 1.3 R3 release includes the following documentation changes:

  • Introduced Skytap Cloud 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 quota.

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.