create.md

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

{% tabs %} {% tab title="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": "example@example.com", "password": "secret123", "firstName": "Jon", "lastName": "Snow", "notificationEmail": "example@example.com"}
x-api-key: 1ba4f98e7c0...
# Returns 201 on success

{% endtab %}

{% tab title="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: 'example@example.com', // 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: 'example@example.com', // 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
});

{% endtab %} {% endtabs %}

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
}