> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shadeform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# /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.

<Note>
  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.
</Note>

See the following tutorials related to instance creation:

<Card href="/getting-started/quickstart#launching-the-instance">
  Creating an Instance
</Card>

<Card href="/guides/dockercontainers">
  Creating an Instance with a Running Container
</Card>

<Card href="/guides/startupscript">
  Creating an Instance with a Startup Script
</Card>


## OpenAPI

````yaml post /instances/create
openapi: 3.0.0
info:
  description: >-
    Shadeform is a single API and platform for deploying and managing cloud
    GPUs.
  version: 1.0.0
  title: Shadeform API
  contact:
    name: Shadeform
    email: support@shadeform.ai
    url: https://www.shadeform.ai
servers:
  - description: Shadeform Production
    url: https://api.shadeform.ai/v1
security:
  - ApiKeyAuth: []
paths:
  /instances/create:
    post:
      summary: /instances/create
      description: >-
        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.
      operationId: InstancesCreate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRequest'
      responses:
        '200':
          description: Returns a CreateResponse object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateResponse'
components:
  schemas:
    CreateRequest:
      type: object
      required:
        - cloud
        - region
        - shade_instance_type
        - shade_cloud
        - name
      properties:
        cloud:
          $ref: '#/components/schemas/Cloud'
        region:
          $ref: '#/components/schemas/Region'
        shade_instance_type:
          $ref: '#/components/schemas/ShadeInstanceType'
        shade_cloud:
          $ref: '#/components/schemas/ShadeCloud'
        name:
          $ref: '#/components/schemas/Name'
        os:
          type: string
          example: ubuntu22.04_cuda12.2_shade_os
          description: The operating system of the instance.
        template_id:
          type: string
          example: template-123
          description: The ID of the template to use for this instance
        launch_configuration:
          $ref: '#/components/schemas/LaunchConfiguration'
        volume_ids:
          type: array
          description: >-
            List of volume IDs to be mounted. Currently only supports 1 volume
            at a time.
          items:
            $ref: '#/components/schemas/VolumeID'
        ssh_key_id:
          $ref: '#/components/schemas/SshKeyID'
        auto_delete:
          $ref: '#/components/schemas/AutoDelete'
        alert:
          $ref: '#/components/schemas/Alert'
        volume_mount:
          $ref: '#/components/schemas/VolumeMount'
        tags:
          type: array
          description: Add custom, searchable tags to instances.
          items:
            $ref: '#/components/schemas/Tag'
        envs:
          type: array
          description: >-
            List of environment variable name and values to automatically add to
            the instance
          items:
            $ref: '#/components/schemas/Env'
    CreateResponse:
      type: object
      required:
        - id
      description: Response of the /instances/create API call
      properties:
        id:
          $ref: '#/components/schemas/Id'
    Cloud:
      type: string
      example: hyperstack
      description: >-
        Specifies the underlying cloud provider. See this
        [explanation](/getting-started/concepts#cloud-cloud-provider) for more
        details.
    Region:
      type: string
      example: canada-1
      description: Specifies the region.
    ShadeInstanceType:
      type: string
      example: A6000
      description: >-
        The Shadeform standardized instance type. See this
        [explanation](/getting-started/concepts#shade-instance-type-and-cloud-instance-type)
        for more details.
    ShadeCloud:
      type: boolean
      example: true
      description: >-
        Specifies if the instance is launched in [Shade
        Cloud](/getting-started/concepts#shade-cloud) or in a linked cloud
        account.
    Name:
      type: string
      example: cool-gpu-server
      description: The name of the instance
    LaunchConfiguration:
      type: object
      required:
        - type
      description: Defines automatic actions after the instance becomes active.
      properties:
        type:
          type: string
          example: docker
          enum:
            - docker
            - script
          description: >-
            Specifies the type of launch configuration. See [Launch
            Configuration](/getting-started/concepts#launch-configuration) for
            more details.
        docker_configuration:
          $ref: '#/components/schemas/DockerConfiguration'
        script_configuration:
          $ref: '#/components/schemas/ScriptConfiguration'
    VolumeID:
      type: string
      example: 78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40
      description: The ID of the storage volume.
    SshKeyID:
      type: string
      example: 78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40
      description: The ID of the SSH Key.
    AutoDelete:
      type: object
      description: Set a date or spend threshold to automatically delete the instance
      properties:
        date_threshold:
          $ref: '#/components/schemas/DateThreshold'
        spend_threshold:
          $ref: '#/components/schemas/SpendThreshold'
    Alert:
      type: object
      description: Set a date or spend threshold to receive an email alert
      properties:
        date_threshold:
          $ref: '#/components/schemas/DateThreshold'
        spend_threshold:
          $ref: '#/components/schemas/SpendThreshold'
    VolumeMount:
      type: object
      description: Settings for mounting volumes onto file systems
      properties:
        auto:
          type: boolean
          description: >-
            Set to true to automatically mount unmounted disks to a default
            filesystem.
    Tag:
      type: string
      example: tag1
      description: Tag for searching and grouping
    Env:
      type: object
      required:
        - name
        - value
      description: Environment variables for the container image.
      properties:
        name:
          type: string
          example: HUGGING_FACE_HUB_TOKEN
          description: Name of the environment variable
        value:
          type: string
          example: hugging_face_api_token
          description: Value of the environment variable
    Id:
      type: string
      format: uuid
      example: d290f1ee-6c54-4b01-90e6-d701748f0851
      description: >-
        The unique identifier for the instance. Used in the instances for the
        /instances/{id}/info and /instances/{id}/delete APIs.
    DockerConfiguration:
      type: object
      required:
        - image
      description: >-
        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.
      properties:
        image:
          type: string
          example: vllm/vllm-openai:latest
          description: >-
            Specifies the docker image to be pulled and run on the instance at
            startup.
        args:
          type: string
          example: '--model mistralai/Mistral-7B-v0.1'
          description: Specifies the container arguments passed into the image at runtime.
        shared_memory_in_gb:
          type: integer
          example: 8
          description: >-
            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:
          type: array
          description: >-
            List of environment variable name-value pairs that will be passed to
            the docker container.
          items:
            $ref: '#/components/schemas/Env'
        port_mappings:
          type: array
          description: >-
            List of port mappings between the host instance and the docker
            container. Equivalent of -p flag for docker run command.
          items:
            $ref: '#/components/schemas/PortMappings'
        volume_mounts:
          type: array
          description: >-
            List of volume mounts between the host instance and the docker
            container. Equivalent of -v flag for docker run command.
          items:
            $ref: '#/components/schemas/VolumeMounts'
        registry_credentials:
          $ref: '#/components/schemas/RegistryCredentials'
    ScriptConfiguration:
      type: object
      required:
        - base64_script
      description: >-
        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.
      properties:
        base64_script:
          type: string
          description: A startup script that is base64 encoded.
          example: >-
            IyEvYmluL2Jhc2gKCiMgRW5kbGVzcyBsb29wCndoaWxlIHRydWUKZG8KICAgICMgRmV0Y2ggYSBjYXQgZmFjdCB3aXRoIGEgbWF4aW11bSBsZW5ndGggb2YgMTQwIGNoYXJhY3RlcnMKICAgIGN1cmwgLS1uby1wcm9ncmVzcy1tZXRlciBodHRwczovL2NhdGZhY3QubmluamEvZmFjdD9tYXhfbGVuZ3RoPTE0MAoKICAgICMgUHJpbnQgYSBuZXdsaW5lIGZvciByZWFkYWJpbGl0eQogICAgZWNobwoKICAgICMgU2xlZXAgZm9yIDMgc2Vjb25kcyBiZWZvcmUgdGhlIG5leHQgaXRlcmF0aW9uCiAgICBzbGVlcCAzCmRvbmUKCgo=
    DateThreshold:
      type: string
      example: '2006-01-02T15:04:05-07:00'
      description: RFC3339 date string
    SpendThreshold:
      type: string
      example: '3.14'
      description: Valid decimal representation of a dollar amount
    PortMappings:
      type: object
      required:
        - host_port
        - container_port
      description: Maps the public instance port to a port on the container.
      properties:
        host_port:
          type: integer
          example: 80
          description: Port of the host.
        container_port:
          type: integer
          example: 8000
          description: Port of the container.
    VolumeMounts:
      type: object
      required:
        - host_path
        - container_path
      description: Mounts the host volume to a container file path.
      properties:
        host_path:
          type: string
          example: ~/.cache/huggingface
          description: Filepath of the host.
        container_path:
          type: string
          example: /root/.cache/huggingface
          description: Filepath of the container.
    RegistryCredentials:
      type: object
      properties:
        username:
          type: string
          example: username
          description: The username for the docker registry.
        password:
          type: string
          example: password
          description: The password for the docker registry.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````