POST /api/v3/envs

Creates an environment from a snapshot or from one or more VM templates

Request Path

POST /api/v3/envs

Request Payload Examples

To create an environment from a specific snapshot in a blueprint:

{
    "environment": {
        "name": "John's Environment",
        "description": "John's Environment Description",
        "projectId": "PRjTcEu83MXmpDAHTf47b-QQ2",
        "policyId": "POLs3J1NEAESn7ipYMwYq20Q2",
        "regionId": "REKolD1-ab84YIxODeMGob9A2",
        "ownerEmail": "projectMember@email.com",
        "teamId": "TMIfWYLs3Y1rIRiSjBj--xCA2"
    },
    "itemsCart": [
        {
            "type": 1,
            "blueprintId": "BPitsTtiUS27hEsHcVZcZsxw2",
            "snapshotId": "SShJUCH6_S8qI6RReprck7tw2"
        }
    ]
}

To create an environment from a custom set of VM templates:

{
    "environment": {
        "name": "John's Environment No. 3",
        "description": "John's Environment Description",
        "projectId": "PRjTcEu83MXmpDAHTf47b-QQ2",
        "policyId": null,
        "regionId": "REKolD1-ab84YIxODeMGob9A2",
        "ownerEmail": "projectMember@email.com",
        "teamId": "TMIfWYLs3Y1rIRiSjBj--xCA2"
    },
    "itemsCart": [
        {
            "type": 2,
            "name": "VM Name",
            "description": "VM Description",
            "templateVmId": "VMyFyls16PYN0dZRUfYIqskA2"
        },
        {
            "type": 2,
            "name": "VM Name 2",
            "description": "VM Description",
            "templateVmId": "VMz08ewmUVWw4CWxjTWE7bxQ2"
        }
    ]
}

Parameters

environment Specifies details of the environment to create.
environment.name A name for the new environment.
environment.description A description for the new environment. Optional.
environment.projectId The ID of the project in which to create the environment. To retrieve available projects, use GET /api/v3/projects.
environment.policyId The environment policy to apply to the new environment. This is required only when creating the environment from a snapshot. For a custom environment from VM templates, the project’s default policy is used.
To retrieve available policies, use GET /api/v3/projects/ID/policies.
To retrieve the ID of a project’s default policy, use GET /api/v3/projects/ID.
environment.regionId The region in which to create the environment. To retrieve available regions, use GET /api/v3/regions.
environment.ownerEmail Defines the environment’s owner. Optional.
If this parameter is omitted the environment will be created under the user that sent the API call
Only Team Managers and Project Managers are able to create an environment and assign it to a different owner under their team/s.
environment.teamId Defines the team that will be associated with the environment. Optional.
This parameter is useful when the owner is associated with multiple teams in a single project.
If this parameter is omitted the environment will be assigned to one of the teams that the owner is member of.
itemsCart Specifies templates from which to build the environment
itemsCart.type The type of a template to be specified for adding to the environment. Possible values:

  • 1. This type can only be specified as the one and only item in the list. It specifies to create an environment from a snapshot in a blueprint.
  • 2. This type can appear one or more times. It specifies to add a VM from a specified VM template.
itemsCart.blueprintId Applicable for a type 1 item in the cart. The ID of the blueprint from which to create the environment. Optional if snapshotId is specified. To retrieve available blueprints, use GET /api/v3/projects/ID/blueprints.
itemsCart.snapshotId Applicable for a type 1 item in the cart. The ID of the snapshot from which to create the environment. Optional. If unspecified, the environment is created from the default snapshot in the specified blueprint. To obtain snapshot IDs, use GET /api/v3/projects/ID/blueprints/ID.
itemsCart.name Applicable for type 2 items in the cart. A name for the VM to add.
itemsCart.description Applicable for type 2 items in the cart. A description for the VM to add.
itemsCart.templateVmId Applicable for type 2 items in the cart. The ID of the VM template from which to create the VM. To retrieve available VM templates, use GET /api/v3/templates.

Response Examples

Creating an environment from a blueprint snapshot:

{
    "resources": {
        "cpuCount": 1,
        "diskSizeMB": 826,
        "memorySizeMB": 128
    },
    "vms": [
        {
            "name": "ApacheSample",
            "description": "My machine",
            "osTypeName": "Linux",
            "imageUrl": "/resources/imgs/cs/machines_icon_orange.png",
            "resources": {
                "cpuCount": 1,
                "diskSizeMB": 826,
                "memorySizeMB": 128
            },
            "domainName": null,
            "internalIPs": [],
            "macAddresses": [],
            "canAddMultipleInstances": true,
            "hostName": "XApacheSample",
            "vanityName": null,
            "httpAccessEnabled": true,
            "startWithHttps": false,
            "user": "root",
            "password": "showmethemoney",
            "id": "MCc2XUhlc4FCSnXs-4r7orTg2"
        }
    ],
    "environmentId": "ENHDFU_rUrgfD1YdDSWJVriQ2"
}

Creating an environment from VM templates:

{
    "resources": {
        "cpuCount": 2,
        "diskSizeMB": 24576,
        "memorySizeMB": 1024
    },
    "vms": [
        {
            "name": "VM Name",
            "description": "VM Description",
            "osTypeName": null,
            "imageUrl": "/ImageHandler.ashx?rXL5DH0iKAm9EtYscPdMAw2",
            "resources": {
                "cpuCount": 1,
                "diskSizeMB": 12288,
                "memorySizeMB": 512
            },
            "domainName": null,
            "internalIPs": [],
            "macAddresses": [],
            "canAddMultipleInstances": true,
            "hostName": null,
            "vanityName": null,
            "httpAccessEnabled": true,
            "startWithHttps": false,
            "user": "Administrator",
            "password": null,
            "id": "MCWDfD3slTbJNGl-MJEcPg7A2"
        },
        {
            "name": "VM Name 2",
            "description": "VM Description",
            "osTypeName": null,
            "imageUrl": "/ImageHandler.ashx?1YTwBlG87xLZFAtVPBGN_Q2",
            "resources": {
                "cpuCount": 1,
                "diskSizeMB": 12288,
                "memorySizeMB": 512
            },
            "domainName": null,
            "internalIPs": [],
            "macAddresses": [],
            "canAddMultipleInstances": true,
            "hostName": null,
            "vanityName": null,
            "httpAccessEnabled": false,
            "startWithHttps": false,
            "user": "Administrator",
            "password": null,
            "id": "MC0J5KBSmuDMJV0rQRvYiqfw2"
        }
    ],
    "environmentId": "ENrwmIocZbHiNDC1p4jLcNPA2"
}

Not all VM information is available at this stage, including password and hostName. To query environment VMs, use GET /api/v3/envs/actions/getextended.