Description of image

Create a Machine with the Paperspace API

Machines are high-performing computing for scaling AI applications.


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


For creating a machine using the API, specify the following parameters in your API call:

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

You can also specify optional parameters, such as autoShutdownEnabled and autoShutdownTimeout to enable auto-shutdown and specify the time after which the machine shuts down.

List Available Templates

You can list the available custom templates using:

# HTTP request:
GET v1/templates
Authorization: Bearer 1ba4f98e7c0...

The command returns 200 on success. The response shows an array of custom templates you have in your account:

    "hasMore": true,
    "nextPage": "tbt2el0a",
    "items": [
            "id": "tbwb4c3s",
            "name": "Test Template - 2/22/2024",
            "isPublic": false,
            "agentType": "LinuxDesktop",
            "operatingSystemLabel": "Ubuntu 22.04",
            "region": "East Coast (NY2)",
            "defaultSizeGb": 500,
            "availableMachineTypes": [
                    "machineTypeLabel": "A100-80G",
                    "isAvailable": true
                    "machineTypeLabel": "A100-80Gx8",
                    "isAvailable": true

To list the OS templates in your account, include the isPublic query parameter. For example, GET

Note the id value of the template you want to use to create a new machine.

Create a Machine

Use the following sample request with the required and optional parameters to create a machine:

# HTTP request:
POST v1/machines {"name": "test machine", "machineType": "P4000", "templateId": "tz0ireoj", "diskSize": 50, "region": "East Coast (NY2)", "autoShutdownEnabled": "true", "autoShutdownTimeout": "6"}
Authorization: Bearer 1ba4f98e7c0...

The command returns 200 on success. The response shows the created machine JSON object:

    "event": {
        "id": "b5b6f23e-7915-45c4-b04a-3145b109b81d",
        "name": "create",
        "state": "new",
        "machineId": "psvv2ew1gd4s",
        "dtCreated": "2024-04-30T15:51:24.565Z",
        "dtStarted": null,
        "dtFinished": null,
        "error": null
    "data": {
        "id": "psvv2ew1gd4s",
        "name": "test machine",
        "state": "provisioning",
        "os": "Ubuntu 20.04 Desktop",
        "machineType": "P4000",
        "agentType": "LinuxDesktop",
        "cpus": 1,
        "ram": "0",
        "storageTotal": "0",
        "storageUsed": "0",
        "accelerators": [
                "name": "Quadro P4000",
                "memory": "8589934592",
                "count": 1
        "region": "East Coast (NY2)",
        "privateIp": null,
        "networkId": null,
        "publicIp": null,
        "publicIpType": "none",
        "autoShutdownEnabled": true,
        "autoShutdownTimeout": 6,

Once the machine is provisioned, you can use GET{id} to get the machine details.

Only an account administrator can perform this create action. Team members cannot create machines themselves; only the team administrator can 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 to 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. You receive a user creation error if the email address is already associated with a Paperspace account.

If you attempt to create a new user along with the machine, the user creation step is executed before the machine is created. Therefore, if an error occurs, the user creation step may or may not have succeeded. To fix 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.