openapi: 3.0.1
info:
  title: Shadeform Instance Types Instances API
  description: Shadeform is a GPU cloud marketplace exposing a single REST API to deploy and manage GPU compute across many underlying clouds. The API standardizes instance types, availability, and per-GPU-hour pricing across providers, and lets you launch, inspect, restart, update, and delete instances, manage persistent volumes and SSH keys, and save reusable launch templates. All requests are authenticated with an X-API-KEY header.
  termsOfService: https://www.shadeform.ai/terms
  contact:
    name: Shadeform Support
    email: info@shadeform.ai
  version: '1.0'
servers:
- url: https://api.shadeform.ai/v1
security:
- ApiKeyAuth: []
tags:
- name: Instances
  description: Launch and manage GPU instances across clouds.
paths:
  /instances:
    get:
      operationId: listInstances
      tags:
      - Instances
      summary: List instances
      description: Retrieve all non-deleted instances for the account. Instances in the 'deleting' status are also returned.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstancesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /instances/create:
    post:
      operationId: createInstance
      tags:
      - Instances
      summary: Create an instance
      description: Launch a new GPU instance on the specified cloud, region, and standardized instance type, optionally with an OS image, launch configuration (Docker or script), volumes, SSH key, auto-delete and alert thresholds, tags, and environment variables.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInstanceRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInstanceResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /instances/{id}/info:
    get:
      operationId: getInstance
      tags:
      - Instances
      summary: Get instance info
      description: Retrieve details for a single instance by its ID.
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /instances/{id}/restart:
    post:
      operationId: restartInstance
      tags:
      - Instances
      summary: Restart an instance
      description: Restart a running instance by its ID.
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      responses:
        '200':
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /instances/{id}/update:
    post:
      operationId: updateInstance
      tags:
      - Instances
      summary: Update an instance
      description: Update mutable properties of an instance, such as its name, tags, auto-delete, or alert configuration.
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInstanceRequest'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /instances/{id}/delete:
    post:
      operationId: deleteInstance
      tags:
      - Instances
      summary: Delete an instance
      description: Delete an instance by its ID, releasing the underlying cloud resources.
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      responses:
        '200':
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ScriptConfiguration:
      type: object
      required:
      - base64_script
      properties:
        base64_script:
          type: string
          description: Base64-encoded startup script.
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    CreateInstanceResponse:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the created instance.
    UpdateInstanceRequest:
      type: object
      properties:
        name:
          type: string
        tags:
          type: array
          items:
            type: string
        auto_delete:
          $ref: '#/components/schemas/AutoDelete'
        alert:
          $ref: '#/components/schemas/Alert'
    DockerConfiguration:
      type: object
      required:
      - image
      properties:
        image:
          type: string
          description: Docker image URI.
        args:
          type: string
        shared_memory_in_gb:
          type: integer
        envs:
          type: array
          items:
            $ref: '#/components/schemas/Env'
        port_mappings:
          type: array
          items:
            $ref: '#/components/schemas/PortMapping'
        volume_mounts:
          type: array
          items:
            $ref: '#/components/schemas/VolumeMount'
        registry_credentials:
          $ref: '#/components/schemas/RegistryCredentials'
    BootTime:
      type: object
      properties:
        min_boot_in_sec:
          type: integer
        max_boot_in_sec:
          type: integer
    Configuration:
      type: object
      description: Hardware and OS configuration of an instance type or instance.
      properties:
        memory_in_gb:
          type: integer
        storage_in_gb:
          type: integer
        vcpus:
          type: integer
        num_gpus:
          type: integer
        gpu_type:
          type: string
        vram_per_gpu_in_gb:
          type: integer
        interconnect:
          type: string
        os_options:
          type: array
          items:
            type: string
    PortMapping:
      type: object
      properties:
        host_port:
          type: integer
        container_port:
          type: integer
    InstancesResponse:
      type: object
      properties:
        instances:
          type: array
          items:
            $ref: '#/components/schemas/Instance'
    LaunchConfiguration:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - docker
          - script
        docker_configuration:
          $ref: '#/components/schemas/DockerConfiguration'
        script_configuration:
          $ref: '#/components/schemas/ScriptConfiguration'
    VolumeMount:
      type: object
      properties:
        host_path:
          type: string
        container_path:
          type: string
    AutoDelete:
      type: object
      description: Triggers that automatically delete the instance.
      properties:
        delete_at:
          type: string
          format: date-time
        spend_limit_in_cents:
          type: integer
    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
      properties:
        id:
          type: string
          format: uuid
        cloud:
          type: string
        region:
          type: string
        shade_instance_type:
          type: string
        cloud_instance_type:
          type: string
        cloud_assigned_id:
          type: string
        shade_cloud:
          type: boolean
        name:
          type: string
        configuration:
          $ref: '#/components/schemas/Configuration'
        ip:
          type: string
          description: Public IP address or DNS name.
        ssh_user:
          type: string
        ssh_port:
          type: integer
        status:
          type: string
          enum:
          - creating
          - pending_provider
          - pending
          - active
          - error
          - deleting
          - deleted
        status_details:
          type: string
        cost_estimate:
          type: string
        hourly_price:
          type: integer
          description: Hourly price in cents.
        launch_configuration:
          $ref: '#/components/schemas/LaunchConfiguration'
        tags:
          type: array
          items:
            type: string
        port_mappings:
          type: array
          items:
            $ref: '#/components/schemas/PortMapping'
        created_at:
          type: string
          format: date-time
        active_at:
          type: string
          format: date-time
        deleted_at:
          type: string
          format: date-time
        boot_time:
          $ref: '#/components/schemas/BootTime'
    Alert:
      type: object
      description: Triggers that send an alert (e.g. email) for the instance.
      properties:
        alert_at:
          type: string
          format: date-time
        spend_limit_in_cents:
          type: integer
        email:
          type: string
    CreateInstanceRequest:
      type: object
      required:
      - cloud
      - region
      - shade_instance_type
      - shade_cloud
      - name
      properties:
        cloud:
          type: string
          description: The cloud provider to launch on.
          example: hyperstack
        region:
          type: string
          example: canada-1
        shade_instance_type:
          type: string
          example: A6000
        shade_cloud:
          type: boolean
          description: Whether to launch through Shade Cloud.
        name:
          type: string
        os:
          type: string
          example: ubuntu22.04_cuda12.2_shade_os
        template_id:
          type: string
          format: uuid
        launch_configuration:
          $ref: '#/components/schemas/LaunchConfiguration'
        volume_ids:
          type: array
          items:
            type: string
            format: uuid
        ssh_key_id:
          type: string
          format: uuid
        auto_delete:
          $ref: '#/components/schemas/AutoDelete'
        alert:
          $ref: '#/components/schemas/Alert'
        tags:
          type: array
          items:
            type: string
        envs:
          type: array
          items:
            $ref: '#/components/schemas/Env'
    Env:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
    RegistryCredentials:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
  parameters:
    InstanceId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: The unique identifier of the instance.
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid X-API-KEY.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key issued from the Shadeform dashboard.