POST
/
instances
/
create
curl --request POST \
  --url https://api.shadeform.ai/v1/instances/create \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "cloud": "hyperstack",
  "region": "canada-1",
  "shade_instance_type": "A6000",
  "shade_cloud": true,
  "name": "cool-gpu-server",
  "os": "ubuntu22.04_cuda12.2_shade_os",
  "template_id": "template-123",
  "launch_configuration": {
    "type": "docker",
    "docker_configuration": {
      "image": "vllm/vllm-openai:latest",
      "args": "--model mistralai/Mistral-7B-v0.1",
      "shared_memory_in_gb": 8,
      "envs": [
        {
          "name": "HUGGING_FACE_HUB_TOKEN",
          "value": "hugging_face_api_token"
        }
      ],
      "port_mappings": [
        {
          "host_port": 80,
          "container_port": 8000
        }
      ],
      "volume_mounts": [
        {
          "host_path": "~/.cache/huggingface",
          "container_path": "/root/.cache/huggingface"
        }
      ]
    },
    "script_configuration": {
      "base64_script": "IyEvYmluL2Jhc2gKCiMgRW5kbGVzcyBsb29wCndoaWxlIHRydWUKZG8KICAgICMgRmV0Y2ggYSBjYXQgZmFjdCB3aXRoIGEgbWF4aW11bSBsZW5ndGggb2YgMTQwIGNoYXJhY3RlcnMKICAgIGN1cmwgLS1uby1wcm9ncmVzcy1tZXRlciBodHRwczovL2NhdGZhY3QubmluamEvZmFjdD9tYXhfbGVuZ3RoPTE0MAoKICAgICMgUHJpbnQgYSBuZXdsaW5lIGZvciByZWFkYWJpbGl0eQogICAgZWNobwoKICAgICMgU2xlZXAgZm9yIDMgc2Vjb25kcyBiZWZvcmUgdGhlIG5leHQgaXRlcmF0aW9uCiAgICBzbGVlcCAzCmRvbmUKCgo="
    }
  },
  "volume_ids": [
    "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40"
  ],
  "ssh_key_id": "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40",
  "auto_delete": {
    "date_threshold": "2006-01-02T15:04:05-07:00",
    "spend_threshold": "3.14"
  },
  "alert": {
    "date_threshold": "2006-01-02T15:04:05-07:00",
    "spend_threshold": "3.14"
  },
  "volume_mount": {
    "auto": true
  },
  "tags": [
    "tag1"
  ],
  "envs": [
    {
      "name": "HUGGING_FACE_HUB_TOKEN",
      "value": "hugging_face_api_token"
    }
  ]
}'
{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "cloud_assigned_id": "13b057d7-e266-4869-985f-760fe75a78b3"
}

The example in the right sidebar is a schema only and will not work out of the box. Only ‘docker_configuration’ or ‘script_configuration’ can be specified but not both.

See the following tutorials related to instance creation:

Creating an Instance

Creating an Instance with a Running Container

Creating an Instance with a Startup Script

Authorizations

​
X-API-KEY
string
header
required

Body

application/json
​
cloud
enum<string>
required

Specifies the underlying cloud provider. See this explanation for more details.

Available options:
aws,
azure,
lambdalabs,
tensordock,
runpod,
latitude,
jarvislabs,
oblivus,
paperspace,
datacrunch,
massedcompute,
vultr
​
region
string
required

Specifies the region.

​
shade_instance_type
string
required

The Shadeform standardized instance type. See this explanation for more details.

​
shade_cloud
boolean
required

Specifies if the instance is launched in Shade Cloud or in a linked cloud account.

​
name
string
required

The name of the instance

​
os
string

The operating system of the instance.

​
template_id
string

The ID of the template to use for this instance

​
launch_configuration
object

Defines automatic actions after the instance becomes active.

​
volume_ids
string[]

List of volume IDs to be mounted. Currently only supports 1 volume at a time.

The ID of the storage volume.

​
ssh_key_id
string

The ID of the SSH Key.

​
auto_delete
object

Set a date or spend threshold to automatically delete the instance

​
alert
object

Set a date or spend threshold to receive an email alert

​
volume_mount
object

Settings for mounting volumes onto file systems

​
tags
string[]

Add custom, searchable tags to instances.

Tag for searching and grouping

​
envs
object[]

List of environment variable name and values to automatically add to the instance

Environment variables for the container image.

Response

200 - application/json
Returns a CreateResponse object

Response of the /instances/create API call

​
id
string
required

The unique identifier for the instance. Used in the instances for the /instances/{id}/info and /instances/{id}/delete APIs.

​
cloud_assigned_id
string
required

The unique identifier of the instance issued by the underlying cloud provider.

/instances/{id}/info