Description of image

Create a Machine with the Core API

Machines are high-performing computing for scaling AI applications.


Visit the Web API page to learn how to authenticate with the Paperspace Web API.


The required parameters are:

  • region (string): Name of the region: either ‘East Coast (NY2)’, ‘West Coast (CA1)’, or ‘Europe (AMS1)’.
  • machineType (string): See the list of Machine Types here.
  • size (number): Storage size for the machine in GB. Uses block storage.
  • billingType (string): ‘hourly’.
  • machineName (string): A name for this machine.
  • templateId (string): Template ID of the template to use for creating this machine (see below for more info).

You can list the available base templates with:

# HTTP request:
GET /templates/getTemplates
x-api-key: 1ba4f98e7c0...
# Returns 200 on success

This returns an array of OS templates as well as any custom templates you have in your account:

// Example return value:
 // A public template:
   "id": "t123abc",
   "name": "paperspace/t123abc",
   "label": "Windows 10",
   "os": "Windows 10 (Server 2016)",
   "dtCreated": "2017-01-03T23:41:06.801Z"
 // A team-owned template:
   "id": "t456def",
   "name": "t456def",
   "label": "New Template 1",
   "os": "Ubuntu 14.04.5 LTS; uname: 4.2.0-27-generic; distro: ubuntu; major: 14; minor: 04",
   "teamId": "te456def",
   "userId": null,
   "region": "East Coast (NY2)",
   "dtCreated": "2017-02-06T18:46:44.882Z"

Create a Machine

Sample request with required and optional parameters:

# HTTP request:
POST /machines/createSingleMachinePublic {"region": "East Coast (NY2)", "machineType": "Air", "size": 50, "billingType": "hourly", "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

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": "",
  "region": null,
  "userId": "u123abc",
  "teamId": "te456def",
  "scriptId": "sc123abc",
  "dtLastRun": null,
  "dynamicPublicIp": null
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.)

Machine Access

Creating a machine using an individual account assigns that account 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.)

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.