Create

Create a new Paperspace virtual machine. If you are using an individual account, you will be assigned as the owner of the machine. If you are a team administrator, you must specify the user that should be assigned to the machine, either by specifying a user id, or by providing an email address, password, first name and last name for the creation of a new user on the team. (The email address must not already be associated with a Paperspace account, otherwise, a user creation error is returned.)

Note: if you attempt to create a new user along with the machine, the user creation step is executed before the creation of the machine. Therefore, if an error occurs, the user creation step may or may not have succeeded. To deal with this, if an error object is returned from the machines create method, subsequently call the users list method (with a search filter specifying the email address) to check if the user creation step succeeded.

Note: machine creation is not always guaranteed to succeed, due to various possible issues such as machine availability, billing issues, resource issues, or system errors. However, you can call the machines availability method to check for current point-in-time availability of a given machine type.

This machine create action can only be performed by an account administrator. (Team members cannot create machines themselves; only the team administrator may do so.)

Examples

HTTP
Node.js
HTTP
# HTTP request:
https://api.paperspace.io
POST /machines/createSingleMachinePublic {"region": "East Coast (NY2)", "machineType": "Air", "size": 50, "billingType": "monthly", "machineName": "My Machine 1", "templateId": "t123abc", "assignPublicIp": true, "networkId": "n123abc", "teamId": "te456def", "email": "[email protected]", "password": "secret123", "firstName": "Jon", "lastName": "Snow", "notificationEmail": "[email protected]"}
x-api-key: 1ba4f98e7c0...
# Returns 201 on success
Node.js
paperspace.machines.create({
region: 'East Coast (NY2)',
machineType: 'Air',
size: 50,
billingType: 'hourly',
machineName: 'My Machine 1',
templateId: 't123abc',
assignPublicIp: true, // optional - assign a new public ip address
networkId: 'n123abc', // optional - only if creating on a specific network
teamId: 'te456def', // optional - required if creating this machine for a team
email: '[email protected]', // optional - if creating a new user
password: 'secret123', // optional - if creating a new user
firstName: 'Jon', // optional - if creating a new user
lastName: 'Snow', // optional - if creating a new user
notificationEmail: '[email protected]', // optional - address to send a notification when complete
scriptId: 'sc123abc', // optional - a script to be run on startup
}, function(err, res) {
// handle error or result
});

Parameters

Name

Type

Attributes

Description

region

string

Name of the region: either 'East Coast (NY2)', 'West Coast (CA1)', or 'Europe (AMS1)'.

machineType

string

Machine type: either 'Air', 'Standard', 'Pro', 'Advanced', 'GPU+', 'P4000', 'P5000', 'P6000', 'V100', 'C1', 'C2', 'C3', 'C4', 'C5', 'C6', 'C7', 'C8', 'C9', or 'C10'

Note: Windows os templates cannot be used to create CPU-only machine types 'C1' - 'C10'. Ubuntu os templates cannot be used to create GRID GPU machine types: 'Air', 'Standard', 'Pro', or 'Advanced'.

size

number

Storage size for the machine in GB.

billingType

string

Either 'monthly' or 'hourly' billing.

machineName

string

A memorable name for this machine.

templateId

string

Template ID of the template to use for creating this machine.

assignPublicIp

boolean

<optional>

Assign a new public ip address on machine creation. Cannot be used with dynamicPublicIp.

dynamicPublicIp

boolean

<optional>

Assigns a new public IP address on machine start and releases it from the account on machine stop. Cannot be used with assignPublicIp.

startOnCreate

boolean

<optional>

Start the VM immediately after creation. Defaults to true.

networkId

string

<optional>

If creating on a specific network, specify its ID

scriptId

string

<optional>

The script ID of a script to be run on startup. See the Script Guide for more info on using scripts.

userId

string

<optional>

If assigning to an existing user other than yourself, specify the user ID (mutually exclusive with email, password, firstName, lastName).

email

string

<optional>

If creating a new user for this machine, specify their email address (mutually exclusive with userId).

password

string

<optional>

If creating a new user, specify their password (mutually exclusive with userId).

firstName

string

<optional>

If creating a new user, specify their first name (mutually exclusive with userId).

lastName

string

<optional>

If creating a new user, specify their last name (mutually exclusive with userId).

notificationEmail

string

<optional>

Send a notification to this email address when complete.

takeInitialSnapshot

boolean

<optional>

Take a snapshot of the VM at first boot.

markSnapshotAsRestorePoint

boolean

<optional>

Use initial snapshot as a restore point for the VM. If this is true, takeInitialSnapshot must be true and restorePointFrequency must be specified.

restorePointFrequency

string

<optional>

How often the VM's restore point should be used. Valid options: shutdown.

Returns

The created machine JSON object

// Example return value:
{
"id": "ps123abc",
"name": "My Machine",
"os": null,
"ram": null,
"cpus": 1,
"gpu": null,
"storageTotal": null,
"storageUsed": null,
"usageRate": "Air hourly",
"shutdownTimeoutInHours": 24,
"shutdownTimeoutForces": false,
"performAutoSnapshot": false,
"autoSnapshotFrequency": null,
"autoSnapshotSaveCount": null,
"agentType": "WindowsDesktop",
"dtCreated": "2017-02-16T20:26:54.880Z",
"state": "provisioning",
"updatesPending": false,
"networkId": null,
"privateIpAddress": null,
"publicIpAddress": "169.255.255.254",
"region": null,
"userId": "u123abc",
"teamId": "te456def",
"scriptId": "sc123abc",
"dtLastRun": null,
"dynamicPublicIp": null
}