Skip to main content

Deploy a Server with the Core API

Creating a server with the Core RESTful API

Prerequisites​

Create an API Key​

An API is required to authenticate requests against the Core API. You can follow the steps on creating an API Key here.

Address for the CORE API HTTP endpoints​

If making HTTP requests directly to the Paperspace API endpoints use the following address for each request: https://api.paperspace.io

Authenticating the CORE API for HTTP requests​

In order to use the HTTP API directly, you must specify the x-api-key header with the value of your API key: 

https://api.paperspace.io
GET /endpoint...
x-api-key: 1ba4f98e7c0...

Parameters​

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. See the volume sizes here.
  • 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:
https://api.paperspace.io
GET /templates/getTemplates
x-api-key: 1ba4f98e7c0...
# Returns 200 on success

This will return an array of base 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:
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

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
}

Note: 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​

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.

Programmatic Access Via the Node.js Client​

In this example, we used the HTTP endpoints to create requests. You can also use the CORE APIs programmatically by creating a Javascript Node.js application and importing the Node.js module. Learn more here.