openapi: 3.1.0
info:
  title: Lambda Cloud File Systems Instances API
  description: The Lambda Cloud API allows you to manage GPU cloud instances programmatically. You can launch, list, restart, and terminate instances, manage SSH keys, list available instance types and images, and manage persistent storage file systems through a RESTful interface.
  version: v1
  contact:
    name: Lambda Support
    url: https://support.lambdalabs.com/hc/en-us
  license:
    name: Lambda Terms of Service
    url: https://lambda.ai/legal/terms-of-service
servers:
- url: https://cloud.lambdalabs.com/api/v1
  description: Lambda Cloud API production endpoint
security:
- apiKey: []
tags:
- name: Instances
  description: Operations for managing GPU cloud instances.
paths:
  /instances:
    get:
      operationId: listInstances
      summary: List Running Instances
      description: Returns a list of all running instances in your account.
      tags:
      - Instances
      responses:
        '200':
          description: A list of running instances.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Instance'
              example:
                data:
                - id: 0920582c7ff041399e34823a0be62549
                  name: training-node-1
                  ip: 10.10.10.1
                  status: active
                  ssh_key_names:
                  - my-ssh-key
                  file_system_names:
                  - my-file-system
                  region:
                    name: us-tx-3
                    description: Austin, Texas
                  instance_type:
                    name: gpu_1x_a100_sxm4
                    description: 1x A100 SXM4 (40 GB)
                  hostname: 10-0-8-196.cloud.lambdalabs.com
                  jupyter_token: 2c60c3b5a671060bc6148900a3ac7a42
                  jupyter_url: https://jupyter-2c60c3b5a671060bc6148900a3ac7a42.cloud.lambdalabs.com
        '401':
          description: Unauthorized - Invalid API key.
        '403':
          description: Forbidden.
        '500':
          description: Internal Server Error.
  /instance-operations/launch:
    post:
      operationId: launchInstance
      summary: Launch An Instance
      description: Launches one or more instances with the given configuration. Returns the IDs of the launched instances.
      tags:
      - Instances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LaunchInstanceRequest'
            example:
              region_name: us-tx-3
              instance_type_name: gpu_1x_a100_sxm4
              ssh_key_names:
              - my-ssh-key
              file_system_names:
              - my-file-system
              quantity: 1
              name: training-node-1
      responses:
        '200':
          description: Instances launched successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      instance_ids:
                        type: array
                        items:
                          type: string
              example:
                data:
                  instance_ids:
                  - 0920582c7ff041399e34823a0be62549
        '400':
          description: Bad Request - Invalid parameters.
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden - Insufficient capacity.
        '500':
          description: Internal Server Error.
  /instance-operations/restart:
    post:
      operationId: restartInstances
      summary: Restart Instances
      description: Restarts the given instances.
      tags:
      - Instances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - instance_ids
              properties:
                instance_ids:
                  type: array
                  items:
                    type: string
                  description: The IDs of the instances to restart.
            example:
              instance_ids:
              - 0920582c7ff041399e34823a0be62549
      responses:
        '200':
          description: Instances restarted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      restarted_instances:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            status:
                              type: string
        '400':
          description: Bad Request.
        '401':
          description: Unauthorized.
        '404':
          description: Instance not found.
        '500':
          description: Internal Server Error.
  /instance-operations/terminate:
    post:
      operationId: terminateInstances
      summary: Terminate Instances
      description: Terminates the given instances.
      tags:
      - Instances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - instance_ids
              properties:
                instance_ids:
                  type: array
                  items:
                    type: string
                  description: The IDs of the instances to terminate.
            example:
              instance_ids:
              - 0920582c7ff041399e34823a0be62549
      responses:
        '200':
          description: Instances terminated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      terminated_instances:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            status:
                              type: string
        '400':
          description: Bad Request.
        '401':
          description: Unauthorized.
        '404':
          description: Instance not found.
        '500':
          description: Internal Server Error.
  /instances/{id}:
    get:
      operationId: getInstance
      summary: Get Instance Details
      description: Returns details for a specific instance.
      tags:
      - Instances
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the instance.
      responses:
        '200':
          description: Instance details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Instance'
        '401':
          description: Unauthorized.
        '404':
          description: Instance not found.
        '500':
          description: Internal Server Error.
components:
  schemas:
    LaunchInstanceRequest:
      type: object
      required:
      - region_name
      - instance_type_name
      - ssh_key_names
      properties:
        region_name:
          type: string
          description: The region to launch the instance in.
        instance_type_name:
          type: string
          description: The type of instance to launch.
        ssh_key_names:
          type: array
          items:
            type: string
          description: SSH key names to attach to the instance.
        file_system_names:
          type: array
          items:
            type: string
          description: File system names to attach to the instance.
        quantity:
          type: integer
          minimum: 1
          maximum: 1
          description: Number of instances to launch (currently max 1).
        name:
          type: string
          description: A name for the instance.
    Instance:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the instance.
        name:
          type: string
          nullable: true
          description: User-provided name for the instance.
        ip:
          type: string
          description: IPv4 address of the instance.
        status:
          type: string
          enum:
          - active
          - booting
          - unhealthy
          - terminated
          description: Current status of the instance.
        ssh_key_names:
          type: array
          items:
            type: string
          description: Names of SSH keys attached to the instance.
        file_system_names:
          type: array
          items:
            type: string
          description: Names of file systems attached to the instance.
        region:
          $ref: '#/components/schemas/Region'
        instance_type:
          type: object
          properties:
            name:
              type: string
            description:
              type: string
        hostname:
          type: string
          description: Hostname of the instance.
        jupyter_token:
          type: string
          description: Token for accessing the Jupyter notebook.
        jupyter_url:
          type: string
          description: URL for accessing the Jupyter notebook.
    Region:
      type: object
      properties:
        name:
          type: string
          description: Region identifier.
        description:
          type: string
          description: Human-readable region name.
  securitySchemes:
    apiKey:
      type: http
      scheme: basic
      description: Use your Lambda Cloud API key as the username with no password. Pass via Authorization header as Basic auth.