---
title: "/instances/create"
method: POST
path: "/instances/create"
---

# /instances/create

`POST /instances/create`

Create a new GPU instance. Our create API is designed to be asynchronous, so the response will be a CreateResponse object with a status of "creating". We then have a process that will pick it up and create it. You can poll the /instances/{id}/info endpoint to check the status of the instance.

## Request body

- CreateRequest
  - `cloud` string, required — Specifies the underlying cloud provider. See this [explanation](/getting-started/concepts#cloud-cloud-provider) for more details.
  - `region` string, required — Specifies the region.
  - `shade_instance_type` string, required — The Shadeform standardized instance type. See this [explanation](/getting-started/concepts#shade-instance-type-and-cloud-instance-type) for more details.
  - `shade_cloud` boolean, required — Specifies if the instance is launched in [Shade Cloud](/getting-started/concepts#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` LaunchConfiguration — Defines automatic actions after the instance becomes active.
    - `type` 'docker' | 'script', required — Specifies the type of launch configuration. See [Launch Configuration](/getting-started/concepts#launch-configuration) for more details.
    - `docker_configuration` DockerConfiguration — May only be used if launch_configuration.type is 'docker'. Use docker_configuration to automatically pull and run a docker image. See this [tutorial](/guides/dockercontainers) for examples.
      - `image` string, required — Specifies the docker image to be pulled and run on the instance at startup.
      - `args` string — Specifies the container arguments passed into the image at runtime.
      - `shared_memory_in_gb` integer — Describes the amount of shared memory allocated for the container. Equivalent to using the --shm-size flag in the docker cli. If shared_memory_in_gb is not specified, then the container will use the host namespace which is the equivalent of --ipc=host.
      - `envs` Env[] — List of environment variable name-value pairs that will be passed to the docker container.
        - `name` string, required — Name of the environment variable
        - `value` string, required — Value of the environment variable
      - `port_mappings` PortMappings[] — List of port mappings between the host instance and the docker container. Equivalent of -p flag for docker run command.
        - `host_port` integer, required — Port of the host.
        - `container_port` integer, required — Port of the container.
      - `volume_mounts` VolumeMounts[] — List of volume mounts between the host instance and the docker container. Equivalent of -v flag for docker run command.
        - `host_path` string, required — Filepath of the host.
        - `container_path` string, required — Filepath of the container.
      - `registry_credentials` RegistryCredentials
        - `username` string — The username for the docker registry.
        - `password` string — The password for the docker registry.
    - `script_configuration` ScriptConfiguration — May only be used if launch_configuration.type is 'script'. Configures a startup script to be run automatically after the instance is active. See this [tutorial]/guides/startupscript) for examples.
      - `base64_script` string, required — A startup script that is base64 encoded.
  - `volume_ids` VolumeID[] — List of volume IDs to be mounted. Currently only supports 1 volume at a time.
  - `ssh_key_id` string — The ID of the SSH Key.
  - `auto_delete` AutoDelete — Set a date or spend threshold to automatically delete the instance
    - `date_threshold` string — RFC3339 date string
    - `spend_threshold` string — Valid decimal representation of a dollar amount
  - `alert` Alert — Set a date or spend threshold to receive an email alert
    - `date_threshold` string — RFC3339 date string
    - `spend_threshold` string — Valid decimal representation of a dollar amount
  - `volume_mount` VolumeMount — Settings for mounting volumes onto file systems
    - `auto` boolean — Set to true to automatically mount unmounted disks to a default filesystem.
  - `tags` Tag[] — Add custom, searchable tags to instances.
  - `envs` Env[] — List of environment variable name and values to automatically add to the instance
    - `name` string, required — Name of the environment variable
    - `value` string, required — Value of the environment variable

## Response `200`

Returns a CreateResponse object

- CreateResponse — Response of the /instances/create API call
  - `id` string, uuid, required — The unique identifier for the instance. Used in the instances for the /instances/{id}/info and /instances/{id}/delete APIs.

---

[API](https://skmtc.net/shadeform/apis/shadeform-api.md) · [All operations](https://skmtc.net/shadeform/apis/shadeform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shadeform/shadeform-api/versions/e1750dca8851/schema)