openapi: 3.0.0
servers:
  - description: Shadeform Production
    url: https://api.shadeform.ai/v1
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
security:
  - ApiKeyAuth: []
paths:
  /instances:
    get:
      summary: /instances
      operationId: Instances
      description: 'Get active and pending instances.'
      responses:
        '200':
          description: 'Returns an InstancesResponse object.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstancesResponse'
  /instances/types:
    get:
      parameters:
        - in: query
          name: cloud
          schema:
            type: string
          example: aws
          description: "Filter the instance type results by cloud."
        - in: query
          name: region
          schema:
            type: string
          example: us-east-1a
          description: "Filter the instance type results by region."
        - in: query
          name: num_gpus
          schema:
            type: string
          example: 1
          description: "Filter the instance type results by the number of gpus."
        - in: query
          name: gpu_type
          schema:
            type: string
          example: A100_80G
          description: "Filter the instance type results by gpu type."
        - in: query
          name: shade_instance_type
          schema:
            type: string
          example: A100_80G
          description: "Filter the instance type results by the shade instance type."
        - in: query
          name: available
          schema:
            type: boolean
          example: true
          description: "Filter the instance type results by availability."
        - in: query
          name: sort
          schema:
            type: string
            enum:
              - price
          example: price
          description: "Sort the order of the instance type results."
      summary: /instances/types
      operationId: InstancesTypes
      description: 'Return all the GPU instance types with their corresponding availability and specs.'
      responses:
        '200':
          description: Returns an InstanceTypesResponse object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceTypesResponse'
  /instances/create:
    post:
      summary: /instances/create
      operationId: InstancesCreate
      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.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRequest'
      responses:
        '200':
          description: Returns a CreateResponse object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateResponse'
  '/instances/{id}/info':
    parameters:
      - in: path
        name: id
        required: true
        example: 'd290f1ee-6c54-4b01-90e6-d701748f0851'
        schema:
          type: string
          minimum: 1
        description: 'The instance id'
    get:
      summary: /instances/{id}/info
      operationId: InstancesInfo
      description: "Get details for the specified instance in the url."
      responses:
        '200':
          description: "Return an instance object."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceInfoResponse'
  '/instances/{id}/update':
    parameters:
      - in: path
        name: id
        required: true
        example: 'd290f1ee-6c54-4b01-90e6-d701748f0851'
        schema:
          type: string
          minimum: 1
        description: 'The instance id'
    post:
      summary: /instances/{id}/update
      operationId: InstancesUpdate
      description: "Update mutable details about the instance. Set a value to null to delete it. Omit a value or leave undefined to keep unchanged."
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRequest'
      responses:
        '200':
          description: 'Confirms the update of an instance.'
  '/instances/{id}/delete':
    parameters:
      - in: path
        name: id
        required: true
        example: 'd290f1ee-6c54-4b01-90e6-d701748f0851'
        schema:
          type: string
          minimum: 1
        description: The instance id
    post:
      summary: /instances/{id}/delete
      operationId: InstancesDelete
      description: "Delete an instance. Some cloud providers may only allow deletion of an instance after it has moved to the 'active' status."
      responses:
        '200':
          description: 'Confirms the deletion of an instance.'
  '/instances/{id}/restart':
    parameters:
      - in: path
        name: id
        required: true
        example: 'd290f1ee-6c54-4b01-90e6-d701748f0851'
        schema:
          type: string
          minimum: 1
        description: The instance id
    post:
      summary: /instances/{id}/restart
      operationId: InstancesRestart
      description: "Restart an instance. The status of the instance will stay as 'active' throughout, but you may have to wait a few minutes for the instance to be ready to use again."
      responses:
        '200':
          description: 'Confirms the restart of an instance has been initiated. This does not confirm that the instance restarted successfully.'
  '/sshkeys':
    get:
      summary: /sshkeys
      operationId: SshKeys
      description: 'Get all SSH Keys for the account.'
      responses:
        '200':
          description: 'Returns an SSHKeysResponse object'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SshKeysResponse'
  '/sshkeys/add':
    post:
      summary: /sshkeys/add
      operationId: SshKeysAdd
      description: 'Add a new SSH Key'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddSshKeyRequest'
      responses:
        '200':
          description: 'Returns a AddSshKeyResponse object'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddSshKeyResponse'
  '/sshkeys/{id}/delete':
    parameters:
      - in: path
        name: id
        required: true
        example: 'd290f1ee-6c54-4b01-90e6-d701748f0851'
        schema:
          type: string
          minimum: 1
        description: 'The ssh key id'
    post:
      summary: /sshkeys/{id}/delete
      operationId: SshKeysDelete
      description: 'Delete an ssh key. The Shadeform managed SSH Key, current default ssh key, and in use SSH Keys cannot be deleted.'
      responses:
        '200':
          description: 'Confirms the deletion of an ssh key.'
  '/sshkeys/{id}/info':
    parameters:
      - in: path
        name: id
        required: true
        example: 'd290f1ee-6c54-4b01-90e6-d701748f0851'
        schema:
          type: string
          minimum: 1
        description: 'The ssh key id'
    get:
      summary: /sshkeys/{id}/info
      operationId: SshKeysInfo
      description: "Get details for the specified SSH Key in the url."
      responses:
        '200':
          description: "Return an SshKey object."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SshKey'
  '/sshkeys/{id}/setdefault':
    parameters:
      - in: path
        name: id
        required: true
        example: 'd290f1ee-6c54-4b01-90e6-d701748f0851'
        schema:
          type: string
          minimum: 1
        description: 'The ssh key id'
    post:
      summary: /sshkeys/{id}/setdefault
      operationId: SshKeysSetDefault
      description: 'Set the specified SSH Key as the default SSH Key used by Shadeform.'
      responses:
        '200':
          description: 'Confirms that the specified SSH Key was as set as the default key.'
  '/volumes':
    get:
      summary: /volumes
      operationId: Volumes
      description: 'Get all storage volumes for the account.'
      responses:
        '200':
          description: 'Returns an VolumesResponse object'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumesResponse'
  '/volumes/create':
    post:
      summary: /volumes/create
      operationId: VolumesCreate
      description: 'Create a new storage volume'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVolumeRequest'
      responses:
        '200':
          description: 'Returns a CreateVolumeResponse object'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateVolumeResponse'
  '/volumes/{id}/delete':
    parameters:
      - in: path
        name: id
        required: true
        example: 'd290f1ee-6c54-4b01-90e6-d701748f0851'
        schema:
          type: string
          minimum: 1
        description: 'The volume id.'
    post:
      summary: /volumes/{id}/delete
      operationId: VolumesDelete
      description: 'Delete a storage volume.'
      responses:
        '200':
          description: 'Confirms the deletion of the specified storage volume.'
  '/volumes/{id}/info':
    parameters:
      - in: path
        name: id
        required: true
        example: 'd290f1ee-6c54-4b01-90e6-d701748f0851'
        schema:
          type: string
          minimum: 1
        description: 'The volume id.'
    get:
      summary: /volumes/{id}/info
      operationId: VolumesInfo
      description: "Get details for the specified storage volume."
      responses:
        '200':
          description: "Return a volume object."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
  '/volumes/types':
    get:
      summary: /volumes/types
      operationId: VolumesTypes
      description: 'Get list of supported storage volumes.'
      responses:
        '200':
          description: 'Returns an VolumesTypesResponse object.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumesTypesResponse'
  '/templates':
    get:
      summary: /templates
      operationId: Templates
      description: 'List all templates created by the user'
      responses:
        '200':
          description: 'Returns a list of templates'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplatesResponse'
  '/templates/featured':
    get:
      summary: /templates/featured
      operationId: TemplatesFeatured
      description: 'List featured templates'
      responses:
        '200':
          description: 'Returns a list of featured templates'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplatesResponse'
  '/templates/{template_id}/info':
    parameters:
      - in: path
        name: template_id
        required: true
        schema:
          type: string
        description: 'The template ID'
    get:
      summary: /templates/{template_id}/info
      operationId: TemplatesInfo
      description: 'Get information about a specific template'
      responses:
        '200':
          description: 'Returns template information'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
  '/templates/save':
    post:
      summary: /templates/save
      operationId: TemplatesSave
      description: 'Create a new template'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateSaveRequest'
      responses:
        '200':
          description: Returns a TemplateCreateResponse object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateCreateResponse'
  '/templates/{template_id}/update':
    parameters:
      - in: path
        name: template_id
        required: true
        schema:
          type: string
        description: 'The template ID'
    post:
      summary: /templates/{template_id}/update
      operationId: TemplatesUpdate
      description: 'Update an existing template'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateSaveRequest'
      responses:
        '200':
          description: 'Template updated successfully'
  '/templates/{template_id}/delete':
    parameters:
      - in: path
        name: template_id
        required: true
        schema:
          type: string
        description: 'The template ID'
    post:
      summary: /templates/{template_id}/delete
      operationId: TemplatesDelete
      description: 'Delete a template'
      responses:
        '200':
          description: 'Template deleted successfully'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
  schemas:
    InstanceTypesResponse:
      description: 'Response of /instances/types'
      type: object
      required:
        - instance_types
      properties:
        instance_types:
          type: array
          items:
            $ref: '#/components/schemas/InstanceType'
    InstanceType:
      description: "Information about a specific instance type"
      type: object
      required:
        - cloud
        - shade_instance_type
        - cloud_instance_type
        - configuration
        - hourly_price
        - deployment_type
        - availability
      properties:
        cloud:
          $ref: '#/components/schemas/Cloud'
        shade_instance_type:
          $ref: '#/components/schemas/ShadeInstanceType'
        cloud_instance_type:
          $ref: '#/components/schemas/CloudInstanceType'
        configuration:
          $ref: '#/components/schemas/InstanceTypeConfiguration'
        hourly_price:
          $ref: '#/components/schemas/HourlyPrice'
        deployment_type:
          $ref: '#/components/schemas/DeploymentType'
        availability:
          type: array
          items:
            $ref: '#/components/schemas/Availability'
          example:
            - region: us-central-1
              available: true
              display_name: US, Wichita, KS
            - region: us-central-2
              available: false
              display_name: US, Wichita, KS
        boot_time:
          $ref: '#/components/schemas/BootTime'
    InstancesResponse:
      type: object
      required:
        - instances
      properties:
        instances:
          type: array
          items:
            $ref: '#/components/schemas/Instance'
    Instance:
      type: object
      required:
        - id
        - cloud
        - region
        - shade_instance_type
        - cloud_instance_type
        - cloud_assigned_id
        - shade_cloud
        - name
        - configuration
        - ip
        - ssh_user
        - ssh_port
        - status
        - cost_estimate
        - created_at
        - deleted_at
      properties:
        id:
          $ref: '#/components/schemas/Id'
        cloud:
          $ref: '#/components/schemas/Cloud'
        region:
          $ref: '#/components/schemas/Region'
        shade_instance_type:
          $ref: '#/components/schemas/ShadeInstanceType'
        cloud_instance_type:
          $ref: '#/components/schemas/CloudInstanceType'
        cloud_assigned_id:
          $ref: '#/components/schemas/CloudAssignedId'
        shade_cloud:
          $ref: '#/components/schemas/ShadeCloud'
        name:
          $ref: '#/components/schemas/Name'
        configuration:
          allOf:
            - $ref: '#/components/schemas/InstanceConfiguration'
            - type: object
              required:
              - os
              properties:
                os:
                  type: string
                  example: ubuntu_22_shade_os
                  description: "The operating system of the instance."
        ip:
          $ref: '#/components/schemas/Ip'
        ssh_user:
          $ref: '#/components/schemas/SshUser'
        ssh_port:
          $ref: '#/components/schemas/SshPort'
        status:
          $ref: '#/components/schemas/Status'
        status_details:
          $ref: '#/components/schemas/StatusDetails'
        cost_estimate:
          $ref: '#/components/schemas/CostEstimate'
        hourly_price:
          $ref: '#/components/schemas/HourlyPrice'
        launch_configuration:
          $ref: '#/components/schemas/LaunchConfiguration'
        tags:
          type: array
          description: 'Add custom, searchable tags to instances.'
          items:
            $ref: '#/components/schemas/Tag'
        port_mappings:
          type: array
          description: 'List of port mappings on an instance that a Cloud Provider might have automatically set up.'
          items:
            $ref: '#/components/schemas/InstancePortMappings'
        active_at:
          $ref: '#/components/schemas/ActiveAt'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        deleted_at:
          $ref: '#/components/schemas/DeletedAt'
        boot_time:
          $ref: '#/components/schemas/BootTime'
    InstanceInfoResponse:
      type: object
      required:
        - id
        - cloud
        - region
        - shade_instance_type
        - cloud_instance_type
        - cloud_assigned_id
        - shade_cloud
        - name
        - configuration
        - ip
        - ssh_user
        - ssh_port
        - status
        - cost_estimate
        - created_at
        - deleted_at
      properties:
        id:
          $ref: '#/components/schemas/Id'
        cloud:
          $ref: '#/components/schemas/Cloud'
        region:
          $ref: '#/components/schemas/Region'
        shade_instance_type:
          $ref: '#/components/schemas/ShadeInstanceType'
        cloud_instance_type:
          $ref: '#/components/schemas/CloudInstanceType'
        cloud_assigned_id:
          $ref: '#/components/schemas/CloudAssignedId'
        shade_cloud:
          $ref: '#/components/schemas/ShadeCloud'
        name:
          $ref: '#/components/schemas/Name'
        configuration:
          allOf:
            - $ref: '#/components/schemas/InstanceConfiguration'
            - type: object
              required:
                - os
              properties:
                os:
                  type: string
                  example: ubuntu_22_shade_os
                  description: "The operating system of the instance."
        ip:
          $ref: '#/components/schemas/Ip'
        ssh_user:
          $ref: '#/components/schemas/SshUser'
        ssh_port:
          $ref: '#/components/schemas/SshPort'
        status:
          $ref: '#/components/schemas/Status'
        status_details:
          $ref: '#/components/schemas/StatusDetails'
        cost_estimate:
          $ref: '#/components/schemas/CostEstimate'
        hourly_price:
          $ref: '#/components/schemas/HourlyPrice'
        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'
        launch_configuration:
          $ref: '#/components/schemas/LaunchConfiguration'
        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'
        port_mappings:
          type: array
          description: 'List of port mappings on an instance that a Cloud Provider might have automatically set up.'
          items:
            $ref: '#/components/schemas/InstancePortMappings'
        active_at:
          $ref: '#/components/schemas/ActiveAt'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        deleted_at:
          $ref: '#/components/schemas/DeletedAt'
        boot_time:
          $ref: '#/components/schemas/BootTime'
    InstanceTypeConfiguration:
      type: object
      required:
        - memory_in_gb
        - storage_in_gb
        - vcpus
        - num_gpus
        - gpu_type
        - interconnect
        - os_options
        - vram_per_gpu_in_gb
      properties:
        memory_in_gb:
          type: integer
          example: 12
          description: "The amount of memory for the instance in gigabytes. Note that this is not VRAM which is determined by GPU type and the number of GPUs."
        storage_in_gb:
          type: integer
          example: 256
          description: 'The amount of storage for the instance. If this storage is too low for the instance type, please email support@shadeform.ai as the storage may be adjustable.'
        vcpus:
          type: integer
          example: 6
          description: "The number of vCPUs for the instance."
        num_gpus:
          type: integer
          example: 1
          description: "The number of GPUs for the instance."
        gpu_type:
          type: string
          example: A100
          description: "The type of GPU for the instance."
        interconnect:
          type: string
          example: pcie
          description: "The type of GPU interconnect."
        nvlink:
          type: boolean
          example: true
          description: "If the instance has NVLink"
        vram_per_gpu_in_gb:
          type: integer
          example: 48
          description: "The video memory per GPU for the instance in gigabytes."
        os_options:
          type: array
          items:
            type: string
          example: [ "ubuntu22.04_cuda12.2_shade_os", "ubuntu20.04_cuda12.0_shade_os" ]
          description: 'The list of available operating systems for the instance.'
    InstanceConfiguration:
      type: object
      required:
        - memory_in_gb
        - storage_in_gb
        - vcpus
        - num_gpus
        - gpu_type
        - interconnect
        - os
        - vram_per_gpu_in_gb
      properties:
        memory_in_gb:
          type: integer
          example: 12
          description: "The amount of memory for the instance in gigabytes. Note that this is not VRAM which is determined by GPU type and the number of GPUs."
        storage_in_gb:
          type: integer
          example: 256
          description: 'The amount of storage for the instance. If this storage is too low for the instance type, please email support@shadeform.ai as the storage may be adjustable.'
        vcpus:
          type: integer
          example: 6
          description: "The number of vCPUs for the instance."
        num_gpus:
          type: integer
          example: 1
          description: "The number of GPUs for the instance."
        gpu_type:
          type: string
          example: A100
          description: "The type of GPU for the instance."
        interconnect:
          type: string
          example: pcie
          description: "The type of GPU interconnect."
        nvlink:
          type: boolean
          example: true
          description: "If the instance has NVLink"
        vram_per_gpu_in_gb:
          type: integer
          example: 48
          description: "The video memory per GPU for the instance in gigabytes."
    Availability:
      type: object
      required:
        - region
        - available
        - display_name
      properties:
        region:
          $ref: '#/components/schemas/Region'
        available:
          type: boolean
          example: true
          description: "Indicate whether the instance is available in the region."
        display_name:
          type: string
          example: "Toronto, Canana"
          description: "The display name of the region"
    BootTime:
      type: object
      properties:
        min_boot_in_sec:
          type: integer
          example: 180
          description: 'boot time minimum estimate'
        max_boot_in_sec:
          type: integer
          example: 300
          description: 'boot time maximum estimate'
    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'

    UpdateRequest:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/Name'
        auto_delete:
          $ref: '#/components/schemas/AutoDelete'
        alert:
          $ref: '#/components/schemas/Alert'
        tags:
          type: array
          description: 'Add custom, searchable tags to instances.'
          items:
            $ref: '#/components/schemas/Tag'

    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'
    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'
    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."
    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=
    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"
    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."
    CreateResponse:
      type: object
      required:
        - id
      description: Response of the /instances/create API call
      properties:
        id:
          $ref: '#/components/schemas/Id'
    Cloud:
      type: string
      example: hyperstack
      enum:
        - lambdalabs
        - paperspace
        - vultr
        - datacrunch
        - latitude
        - massedcompute
        - imwt
        - hyperstack
        - nebius
        - crusoe
        - denvr
        - digitalocean
        - tcm
        - hotaisle
        - cudo
        - scaleway
        - evergreen
        - excesssupply
        - voltagepark
        - boostrun
        - ionstream
        - whitefiber
        - horizon
        - fpt
        - hydra
        - amaya
      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.'
    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.'
    CloudAssignedId:
      type: string
      example: 13b057d7-e266-4869-985f-760fe75a78b3
      description: 'The unique identifier of the instance issued by the underlying cloud provider.'
    Name:
      type: string
      example: cool-gpu-server
      description: The name of the instance
    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.'
    CloudInstanceType:
      type: string
      example: gpu_1x_a6000
      description: 'The instance type for the underlying cloud provider. See this [explanation](/getting-started/concepts#shade-instance-type-and-cloud-instance-type) for more details.'
    HourlyPrice:
      type: integer
      example: 210
      description: 'The hourly price of the instance in cents.'
    DeploymentType:
      type: string
      example: vm
      description: 'Whether the instance is a "vm" (virtual machine), a "container" (docker container), or "baremetal" (bare metal server).'
    Ip:
      type: string
      example: 1.0.0.1
      description: 'The public IP address of the instance. In select cases, it may also be the DNS.'
    SshUser:
      type: string
      example: shadeform
      description: 'The SSH user used to SSH into the instance.'
    SshPort:
      type: integer
      example: 22
      description: 'The SSH port of the instance. In most cases, this will be port 22 but for some clouds, this may be a different port.'
    Status:
      type: string
      example: active
      enum:
        - creating
        - pending_provider
        - pending
        - active
        - deleted
      description: 'The status of the instance.'
    StatusDetails:
      type: string
      example: downloading
      description: 'Additional context for the status'
    CostEstimate:
      type: string
      example: '103.4'
      description: 'The cost incurred by the instance. This only the cost via Shadeform. If the instance is deployed in your own cloud account, then all billing is through your cloud provider.'
    ActiveAt:
      type: string
      format: date-time
      example: '2016-08-29T09:12:33.001Z'
      description: 'The timestamp of when the instance was active in UTC.'
    CreatedAt:
      type: string
      format: date-time
      example: '2016-08-29T09:12:33.001Z'
      description: 'The timestamp of when the instance was created in UTC.'
    DeletedAt:
      type: string
      format: date-time
      example: '2016-08-29T09:12:33.001Z'
      description: 'The timestamp of when the instance was deleted in UTC.'
    SshKeysResponse:
      type: object
      required:
        - ssh_keys
      properties:
        ssh_keys:
          type: array
          items:
            $ref: '#/components/schemas/SshKey'
    SshKey:
      type: object
      required:
        - id
        - name
        - public_key
        - is_default
      properties:
        id:
          $ref: '#/components/schemas/SshKeyID'
        name:
          $ref: '#/components/schemas/SshKeyName'
        public_key:
          $ref: '#/components/schemas/PublicKey'
        is_default:
          $ref: '#/components/schemas/IsDefault'
    AddSshKeyRequest:
      type: object
      required:
        - name
        - public_key
      properties:
        name:
          $ref: '#/components/schemas/SshKeyName'
        public_key:
          $ref: '#/components/schemas/PublicKey'
    AddSshKeyResponse:
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/SshKeyID'
    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'
    InstancePortMappings:
      type: object
      description: 'List of port mappings on an instance that a Cloud Provider might have automatically set up.'
      properties:
        internal_port:
          type: integer
          example: 8000
        external_port:
          type: integer
          example: 80   
    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'
    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'
    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.'


    SshKeyName:
      type: string
      example: 'My ssh key'
      description: "The name of the SSH Key."
    PublicKey:
      type: string
      example: 'ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAklOUpkDHrfHY17SbrmTIpNLTGK9Tjom/BWDSU GPl+nafzlHDTYW7hdI4yZ5ew18JH4JW9jbhUFrviQzM7xlELEVf4h9lFX5QVkbPppSwg0cda3 Pbv7kOdJ/MTyBlWXFCR+HAo3FXRitBqxiX1nKhXpHAZsMciLq8V6RjsNAQwdsdMFvSlVK/7XA t3FaoJoAsncM1Q9x5+3V0Ww68/eIFmb1zuUFljQJKprrX88XypNDvjYNby6vw/Pb0rwert/En mZ+AW4OZPnTPI89ZPmVMLuayrD2cE86Z/il8b+gw3r3+1nKatmIkjn2so1d01QraTlMqVSsbx NrRFi9wrf+M7Q== schacon@mylaptop.local'
      description: "The public key."
    IsDefault:
      type: boolean
      example: false
      description: "Indicates the default key."
    Tag:
      type: string
      example: "tag1"
      description: "Tag for searching and grouping"

    VolumesResponse:
      type: object
      required:
        - volumes
      properties:
        volumes:
          type: array
          items:
            $ref: '#/components/schemas/Volume'
    CreateVolumeRequest:
      type: object
      required:
        - cloud
        - region
        - size_in_gb
        - name
      properties:
        cloud:
          $ref: '#/components/schemas/Cloud'
        region:
          $ref: '#/components/schemas/Region'
        size_in_gb:
          $ref: '#/components/schemas/VolumeSizeInGB'
        name:
          $ref: '#/components/schemas/VolumeName'
    CreateVolumeResponse:
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/VolumeID'
    VolumesTypesResponse:
      type: object
      required:
        - volume_types
      properties:
        volume_types:
          $ref: '#/components/schemas/VolumeTypes'
    Volume:
      type: object
      required:
        - id
        - cloud
        - cloud_assigned_id
        - region
        - name
        - fixed_size
        - size_in_gb
        - cost_estimate
        - supports_multi_mount
        - mounted_by
      properties:
        id:
          $ref: '#/components/schemas/VolumeID'
        cloud:
          $ref: '#/components/schemas/Cloud'
        cloud_assigned_id:
          $ref: '#/components/schemas/VolumeCloudAssignedId'
        region:
          $ref: '#/components/schemas/Region'
        name:
          $ref: '#/components/schemas/VolumeName'
        fixed_size:
          $ref: '#/components/schemas/VolumeFixedSize'
        size_in_gb:
          $ref: '#/components/schemas/VolumeSizeInGB'
        cost_estimate:
          $ref: '#/components/schemas/CostEstimate'
        supports_multi_mount:
          $ref: '#/components/schemas/VolumeSupportsMultiMount'
        mounted_by:
          $ref: '#/components/schemas/VolumeMountedBy'
    VolumeID:
      type: string
      example: '78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40'
      description: 'The ID of the storage volume.'
    VolumeName:
      type: string
      example: 'My storage volume'
      description: 'The name of the storage volume.'
    VolumeCloudAssignedId:
      type: string
      example: '13b057d7-e266-4869-985f-760fe75a78b3'
      description: 'The unique identifier of the storage volume issued by the underlying cloud provider.'
    VolumeFixedSize:
      type: boolean
      example: true
      description: 'Denotes whether the volume is fixed in size or elastically scaling.'
    VolumeSizeInGB:
      type: integer
      example: 100
      description: 'Storage volume size in GB'
    VolumeCostEstimate:
      type: string
      example: '12.01'
      description: 'Cost incurred by the storage volume'
    VolumeSupportsMultiMount:
      type: boolean
      example: true
      description: 'Denotes whether the volume supports multiple instances mounting to it at the same time.'
    VolumeMountedBy:
      type: string
      example: '13b057d7-e266-4869-985f-760fe75a78b3'
      description: 'The ID of the instance that is currently mounting the volume.'
    VolumePricePerGBPerHour:
      type: string
      example: '0.0001'
      description: 'Price of the specified volume type per GB per hour'
    VolumeTypes:
      type: array
      items:
        type: object
        required:
          - cloud
          - region
          - supports_multi_mount
          - fixed_size
          - price_per_gb_per_hour
        properties:
          cloud:
            $ref: '#/components/schemas/Cloud'
          region:
            $ref: '#/components/schemas/Region'
          supports_multi_mount:
            $ref: '#/components/schemas/VolumeSupportsMultiMount'
          fixed_size:
            $ref: '#/components/schemas/VolumeFixedSize'
          price_per_gb_per_hour:
            $ref: '#/components/schemas/VolumePricePerGBPerHour'
    
    Template:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          example: "d290f1ee-6c54-4b01-90e6-d701748f0851"
          description: "Unique identifier for the template, generated by Shadeform"
        name:
          type: string
          example: "My AwesomeTemplate"
          description: "Name of the template"
        description:
          type: string
          example: "A template for running vLLM"
          description: "Description of the template"
        author:
          type: string
          example: "John Doe"
          description: "Author of the template"
        logo:
          type: string
          example: "https://example.com/logo.png"
          description: "URL to the template's logo"
        public:
          type: boolean
          example: true
          description: "Whether the template is publicly available"
        launch_configuration:
          $ref: '#/components/schemas/LaunchConfiguration'
        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'
        networking:
          $ref: '#/components/schemas/Networking'
          description: "Network and firewall configuration"

    TemplatesResponse:
      type: object
      required:
        - templates
      properties:
        templates:
          type: array
          items:
            $ref: '#/components/schemas/Template'

    FeaturedTemplate:
      type: object
      required:
        - name
        - description
        - public
      properties:
        name:
          type: string
          example: "Featured Template"
          description: "Name of the featured template"
        description:
          type: string
          example: "A featured template for ML workloads"
          description: "Description of the featured template"
        public:
          type: boolean
          example: true
          description: "Whether the template is publicly available"
        launch_configuration:
          type: object
          description: "Configuration for launching the instance"
        auto_delete:
          type: object
          description: "Auto-deletion configuration"
        alert:
          type: object
          description: "Alert configuration"
        volume_mount:
          type: object
          description: "Volume mount configuration"
        tags:
          type: array
          items:
            type: string
          example: ["ml", "pytorch"]
          description: "Tags associated with the template"
        envs:
          type: array
          items:
            $ref: '#/components/schemas/Env'
          description: "Environment variables for the template"
        networking:
          $ref: '#/components/schemas/Networking'
          description: "Network and firewall configuration"

    FeaturedTemplatesResponse:
      type: object
      required:
        - templates
      properties:
        templates:
          type: array
          items:
            $ref: '#/components/schemas/FeaturedTemplate'

    TemplateSaveRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: "My Template"
          description: "Name of the template"
        description:
          type: string
          example: "A template for ML workloads"
          description: "Description of the template"
        public:
          type: boolean
          example: true
          description: "Whether the template is publicly available"
        launch_configuration:
          $ref: '#/components/schemas/LaunchConfiguration'
        auto_delete:
          $ref: '#/components/schemas/AutoDelete'
        alert:
          $ref: '#/components/schemas/Alert'
          description: "Alert configuration"
        volume_mount:
          $ref: '#/components/schemas/VolumeMount'
          description: "Volume mount configuration"
        tags:
          type: array
          items:
            type: string
          example: ["ml", "pytorch"]
          description: "Tags associated with the template"
        envs:
          type: array
          items:
            $ref: '#/components/schemas/Env'
          description: "Environment variables for the template"
        networking:
          $ref: '#/components/schemas/Networking'
          description: "Network and firewall configuration"

    Networking:
      type: object
      description: "Network configuration including firewall rules"
      properties:
        ufw_rules:
          type: array
          items:
            $ref: '#/components/schemas/UfwRule'
          description: "List of UFW (Uncomplicated Firewall) rules"

    UfwRule:
      type: object
      description: "Uncomplicated Firewall rule configuration"
      properties:
        rule:
          type: string
          example: "allow"
          description: "The UFW rule action"
        from_ip:
          type: string
          example: "192.168.1.0/24"
          nullable: true
          description: "Source IP address or CIDR range"
        to_ip:
          type: string
          example: "10.0.0.0/8"
          nullable: true
          description: "Destination IP address or CIDR range"
        port:
          type: string
          example: "80"
          nullable: true
          description: "Port number or range (e.g. '80' or '8000:8999')"
        proto:
          type: string
          example: "tcp"
          nullable: true
          description: "Protocol (e.g. tcp, udp)"
    TemplateCreateResponse:
        type: object
        required:
          - id
        description: Response of the /templates/save API call
        properties:
          id:
            $ref: '#/components/schemas/Id'