Mithril Instances API

openapi: 3.2.0
info:
  title: Mithril Instances API
  description: Mithril Compute API
  version: 1.0.0
servers:
- url: https://api.mithril.ai
tags:
- name: Instances
paths:
  /v2/instances:
    get:
      tags:
      - Instances
      summary: Get Instances
      description: Get all instances for a project
      operationId: get_instances_v2_instances_get
      security:
      - MithrilAPIKey: []
      parameters:
      - name: next_cursor
        in: query
        required: false
        schema:
          nullable: true
      - name: sort_by
        in: query
        required: false
        schema:
          enum:
          - created_at
          - instance_status
          - instance_type_fid
          type: string
          nullable: true
      - name: sort_dir
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortDirection'
          nullable: true
      - name: project
        in: query
        required: true
        schema:
          type: string
          title: Project
      - name: instance_type
        in: query
        required: false
        schema:
          type: string
          examples:
          - it_abc123456
          nullable: true
      - name: region
        in: query
        required: false
        schema:
          type: string
          examples:
          - us-central1-a
          nullable: true
      - name: status_in
        in: query
        required: false
        schema:
          type: array
          items:
            enum:
            - STATUS_NEW
            - STATUS_CONFIRMED
            - STATUS_INITIALIZING
            - STATUS_STARTING
            - STATUS_RUNNING
            - STATUS_STOPPING
            - STATUS_TERMINATED
            - STATUS_RELOCATING
            - STATUS_PREEMPTING
            - STATUS_PREEMPTED
            - STATUS_REPLACED
            - STATUS_PAUSED
            - STATUS_ERROR
            type: string
          description: Comma-separated list of instance statuses
          nullable: true
      - name: order_type_in
        in: query
        required: false
        schema:
          type: array
          items:
            enum:
            - Bid
            - Reservation
            type: string
          description: Comma-separated list of order types
          nullable: true
      - name: bid_fid_in
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            examples:
            - bid_abc123456
          description: Comma-separated list of bid FIDs
          nullable: true
      - name: reservation_fid_in
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            examples:
            - res_abc123456
          description: Comma-separated list of reservation FIDs
          nullable: true
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          nullable: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInstancesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Instances
      summary: Put Instance Status
      description: 'Trigger a status change for a set of instances.


        This endpoint supports batch start and pause requests for instances. The

        request accepts a set of instance FIDs and a target action

        (`STATUS_RUNNING` or `STATUS_PAUSED`).


        The response always includes an entry for every requested instance, keyed by

        instance FID, with that instance''s current status after processing.

        - When an instance is successfully starting, its status is `STATUS_CONFIRMED`.

        - When an instance is successfully stopping, its status is `STATUS_STOPPING`.

        - If an instance cannot be stopped, its prior status is returned unchanged.


        Paused instances which are associated with a reservation will accrue a

        credit based on the flexible usage buyback price on that reservation.


        Notes:

        - Only reserved instances are supported at this time.

        - This API is asynchronous. You can check the status of the instance with the

        Get Status api.'
      operationId: put_instance_status_v2_instances_patch
      security:
      - MithrilAPIKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchInstanceStatusRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchInstanceStatusResponse'
        '404':
          description: One of the provided instances did not exist.
        '501':
          description: Spot bids are not yet supported.
        '409':
          description: One or more of the instances is not yet ready for this operation.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/instances/{instance_fid}/status:
    get:
      tags:
      - Instances
      summary: Get Instance Status
      description: 'Get the status of a specific instance by its ID.

        Supports authentication via mithril key or API key.'
      operationId: get_instance_status_v2_instances__instance_fid__status_get
      security:
      - MithrilAPIKey: []
      parameters:
      - name: instance_fid
        in: path
        required: true
        schema:
          type: string
          examples:
          - inst_abc123456
          title: Instance Fid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/instances/{instance_fid}/refresh-boot-disk:
    post:
      tags:
      - Instances
      summary: Refresh Instance Boot Disk
      description: 'Refresh (delete and recreate) the boot disk of a reserved instance.


        The instance must already be stopped: stop it first via the pause API

        (`PATCH /instances` with `STATUS_PAUSED`), then call this endpoint, then

        start it again. A running instance is declined; this endpoint never

        stops the instance itself. When `image_version` is omitted the current

        boot image is reused.


        Notes:

        - Only reserved (non-spot) instances are supported at this time.

        - This is being rolled out across all our regions.'
      operationId: refresh_instance_boot_disk_v2_instances__instance_fid__refresh_boot_disk_post
      security:
      - MithrilAPIKey: []
      parameters:
      - name: instance_fid
        in: path
        required: true
        schema:
          type: string
          examples:
          - inst_abc123456
          title: Instance Fid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshBootDiskRequest'
              nullable: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshBootDiskResponse'
        '404':
          description: The instance does not exist.
        '501':
          description: Boot disk refresh is not supported for this instance yet (spot instances, or not yet available in this instance's region).
        '409':
          description: The instance has no underlying VM to refresh.
        '422':
          description: The instance is still running, or the requested image version is invalid for the instance's region. The body carries a `reason` of INSTANCE_RUNNING or INVALID_IMAGE_VERSION.
  /v2/instances/status/history:
    get:
      tags:
      - Instances
      summary: Get Instance Status History
      description: 'Get the history of a specific instance by its ID,

        or of all instances in a bid or reservation.'
      operationId: get_instance_status_history_v2_instances_status_history_get
      security:
      - MithrilAPIKey: []
      parameters:
      - name: project
        in: query
        required: true
        schema:
          type: string
          examples:
          - proj_abc123456
          title: Project
      - name: instance_fid
        in: query
        required: false
        schema:
          type: string
          examples:
          - inst_abc123456
          nullable: true
      - name: bid_fid
        in: query
        required: false
        schema:
          type: string
          examples:
          - bid_abc123456
          nullable: true
      - name: reservation_fid
        in: query
        required: false
        schema:
          type: string
          examples:
          - res_abc123456
          nullable: true
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          nullable: true
      - name: start_time
        in: query
        required: false
        schema:
          examples:
          - '2024-01-01T00:00:00Z'
          - '2024-01-01T00:00:00+00:00'
          - '2024-01-01T00:00:00-00:00'
          type: string
          format: datetime
          nullable: true
      - name: end_time
        in: query
        required: false
        schema:
          examples:
          - '2024-01-01T00:00:00Z'
          - '2024-01-01T00:00:00+00:00'
          - '2024-01-01T00:00:00-00:00'
          type: string
          format: datetime
          nullable: true
      - name: next_cursor
        in: query
        required: false
        schema:
          type: string
          nullable: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceStatusHistoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/instances/pricing/history:
    get:
      tags:
      - Instances
      summary: Get Instance Pricing History
      description: 'Get the pricing history of a specific instance by its ID,

        or of all instances in a bid or reservation.'
      operationId: get_instance_pricing_history_v2_instances_pricing_history_get
      security:
      - MithrilAPIKey: []
      parameters:
      - name: project
        in: query
        required: true
        schema:
          type: string
          examples:
          - proj_abc123456
          title: Project
      - name: instance_fid
        in: query
        required: false
        schema:
          type: string
          examples:
          - inst_abc123456
          nullable: true
      - name: bid_fid
        in: query
        required: false
        schema:
          type: string
          examples:
          - bid_abc123456
          nullable: true
      - name: reservation_fid
        in: query
        required: false
        schema:
          type: string
          examples:
          - res_abc123456
          nullable: true
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          nullable: true
      - name: start_time
        in: query
        required: false
        schema:
          examples:
          - '2024-01-01T00:00:00Z'
          - '2024-01-01T00:00:00+00:00'
          - '2024-01-01T00:00:00-00:00'
          type: string
          format: datetime
          nullable: true
      - name: end_time
        in: query
        required: false
        schema:
          examples:
          - '2024-01-01T00:00:00Z'
          - '2024-01-01T00:00:00+00:00'
          - '2024-01-01T00:00:00-00:00'
          type: string
          format: datetime
          nullable: true
      - name: next_cursor
        in: query
        required: false
        schema:
          type: string
          nullable: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstancePricingHistoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    InstanceStatusResponse:
      properties:
        fid:
          type: string
          title: Fid
          examples:
          - inst_abc123456
        name:
          type: string
          title: Name
        status:
          type: string
          enum:
          - STATUS_NEW
          - STATUS_CONFIRMED
          - STATUS_INITIALIZING
          - STATUS_STARTING
          - STATUS_RUNNING
          - STATUS_STOPPING
          - STATUS_TERMINATED
          - STATUS_RELOCATING
          - STATUS_PREEMPTING
          - STATUS_PREEMPTED
          - STATUS_REPLACED
          - STATUS_PAUSED
          - STATUS_ERROR
          title: Status
          examples:
          - STATUS_NEW
          - STATUS_CONFIRMED
          - STATUS_INITIALIZING
          - STATUS_STARTING
          - STATUS_RUNNING
          - STATUS_STOPPING
          - STATUS_TERMINATED
          - STATUS_RELOCATING
          - STATUS_PREEMPTING
          - STATUS_PREEMPTED
          - STATUS_REPLACED
          - STATUS_PAUSED
          - STATUS_ERROR
        bid:
          type: string
          examples:
          - bid_abc123456
          nullable: true
        reservation:
          type: string
          examples:
          - res_abc123456
          nullable: true
        end_time:
          type: string
          format: datetime
          examples:
          - '2024-01-01T00:00:00Z'
          - '2024-01-01T00:00:00+00:00'
          - '2024-01-01T00:00:00-00:00'
          nullable: true
      type: object
      required:
      - fid
      - name
      - status
      title: InstanceStatusResponse
      description: Response model for instance status endpoint.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RefreshBootDiskRequest:
      properties:
        image_version:
          type: string
          examples:
          - imgver_abc123456
          nullable: true
      type: object
      title: RefreshBootDiskRequest
      description: 'Request body for the refresh-boot-disk endpoint.


        The body is optional; when ``image_version`` is omitted the instance''s

        current boot image is reused.'
    InstanceStatusHistory:
      properties:
        instance_fid:
          type: string
          title: Instance Fid
          examples:
          - inst_abc123456
        events:
          items:
            $ref: '#/components/schemas/InstanceStatusEvent'
          type: array
          title: Events
        bid_fid:
          type: string
          examples:
          - bid_abc123456
          nullable: true
        reservation_fid:
          type: string
          examples:
          - res_abc123456
          nullable: true
      type: object
      required:
      - instance_fid
      - events
      title: InstanceStatusHistory
      description: The history of an instance's status.
    InstanceModel:
      properties:
        fid:
          type: string
          title: Fid
          examples:
          - inst_abc123456
        name:
          type: string
          title: Name
        project:
          type: string
          title: Project
          examples:
          - proj_abc123456
        created_at:
          type: string
          format: datetime
          title: Created At
          examples:
          - '2024-01-01T00:00:00Z'
          - '2024-01-01T00:00:00+00:00'
          - '2024-01-01T00:00:00-00:00'
        created_by:
          type: string
          title: Created By
          examples:
          - user_abc123456
        instance_type:
          type: string
          title: Instance Type
          examples:
          - it_abc123456
        region:
          type: string
          examples:
          - us-central1-a
          nullable: true
        bid:
          type: string
          examples:
          - bid_abc123456
          nullable: true
        reservation:
          type: string
          examples:
          - res_abc123456
          nullable: true
        ssh_destination:
          type: string
          nullable: true
        private_ip:
          type: string
          nullable: true
        status:
          type: string
          enum:
          - STATUS_NEW
          - STATUS_CONFIRMED
          - STATUS_INITIALIZING
          - STATUS_STARTING
          - STATUS_RUNNING
          - STATUS_STOPPING
          - STATUS_TERMINATED
          - STATUS_RELOCATING
          - STATUS_PREEMPTING
          - STATUS_PREEMPTED
          - STATUS_REPLACED
          - STATUS_PAUSED
          - STATUS_ERROR
          title: Status
          examples:
          - STATUS_NEW
          - STATUS_CONFIRMED
          - STATUS_INITIALIZING
          - STATUS_STARTING
          - STATUS_RUNNING
          - STATUS_STOPPING
          - STATUS_TERMINATED
          - STATUS_RELOCATING
          - STATUS_PREEMPTING
          - STATUS_PREEMPTED
          - STATUS_REPLACED
          - STATUS_PAUSED
          - STATUS_ERROR
      type: object
      required:
      - fid
      - name
      - project
      - created_at
      - created_by
      - instance_type
      - status
      title: InstanceModel
    SortDirection:
      type: string
      enum:
      - asc
      - desc
    InstanceStatusEvent:
      properties:
        timestamp:
          type: string
          format: datetime
          title: Timestamp
          examples:
          - '2024-01-01T00:00:00Z'
          - '2024-01-01T00:00:00+00:00'
          - '2024-01-01T00:00:00-00:00'
        status:
          type: string
          enum:
          - STATUS_NEW
          - STATUS_CONFIRMED
          - STATUS_INITIALIZING
          - STATUS_STARTING
          - STATUS_RUNNING
          - STATUS_STOPPING
          - STATUS_TERMINATED
          - STATUS_RELOCATING
          - STATUS_PREEMPTING
          - STATUS_PREEMPTED
          - STATUS_REPLACED
          - STATUS_PAUSED
          - STATUS_ERROR
          title: Status
      type: object
      required:
      - timestamp
      - status
      title: InstanceStatusEvent
      description: An event in the history of an instance's status.
    GetInstancesResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/InstanceModel'
          type: array
          title: Data
        next_cursor:
          type: string
          nullable: true
      type: object
      required:
      - data
      title: GetInstancesResponse
    InstanceStatusHistoryResponse:
      properties:
        instances:
          items:
            $ref: '#/components/schemas/InstanceStatusHistory'
          type: array
          title: Instances
        next_cursor:
          type: string
          nullable: true
      type: object
      required:
      - instances
      title: InstanceStatusHistoryResponse
      description: Response model for instance status history endpoint.
    PatchInstanceStatusRequest:
      properties:
        instances:
          items:
            type: string
            examples:
            - inst_abc123456
          type: array
          uniqueItems: true
          title: Instances
        status:
          type: string
          enum:
          - STATUS_RUNNING
          - STATUS_PAUSED
          title: Status
      type: object
      required:
      - instances
      - status
      title: PatchInstanceStatusRequest
    InstancePricingHistoryResponse:
      properties:
        instances:
          items:
            $ref: '#/components/schemas/InstancePricingHistory'
          type: array
          title: Instances
        next_cursor:
          type: string
          nullable: true
      type: object
      required:
      - instances
      title: InstancePricingHistoryResponse
      description: Response model for instance pricing history endpoint.
    InstancePricingEvent:
      properties:
        price_cents:
          type: integer
          title: Price Cents
        start_time:
          type: string
          format: datetime
          title: Start Time
          examples:
          - '2024-01-01T00:00:00Z'
          - '2024-01-01T00:00:00+00:00'
          - '2024-01-01T00:00:00-00:00'
        end_time:
          type: string
          format: datetime
          examples:
          - '2024-01-01T00:00:00Z'
          - '2024-01-01T00:00:00+00:00'
          - '2024-01-01T00:00:00-00:00'
          nullable: true
      type: object
      required:
      - price_cents
      - start_time
      - end_time
      title: InstancePricingEvent
      description: A price period in the history of an instance.
    PatchInstanceStatusResponse:
      properties:
        instances:
          additionalProperties:
            type: string
            enum:
            - STATUS_NEW
            - STATUS_CONFIRMED
            - STATUS_INITIALIZING
            - STATUS_STARTING
            - STATUS_RUNNING
            - STATUS_STOPPING
            - STATUS_TERMINATED
            - STATUS_RELOCATING
            - STATUS_PREEMPTING
            - STATUS_PREEMPTED
            - STATUS_REPLACED
            - STATUS_PAUSED
            - STATUS_ERROR
          propertyNames:
            examples:
            - inst_abc123456
          type: object
          title: Instances
      type: object
      required:
      - instances
      title: PatchInstanceStatusResponse
    ValidationError:
      properties:
        loc:
          items:
            oneOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    InstancePricingHistory:
      properties:
        instance_fid:
          type: string
          title: Instance Fid
          examples:
          - inst_abc123456
        events:
          items:
            $ref: '#/components/schemas/InstancePricingEvent'
          type: array
          title: Events
        bid_fid:
          type: string
          examples:
          - bid_abc123456
          nullable: true
        reservation_fid:
          type: string
          examples:
          - res_abc123456
          nullable: true
      type: object
      required:
      - instance_fid
      - events
      title: InstancePricingHistory
      description: The history of an instance's pricing.
    RefreshBootDiskResponse:
      properties:
        fid:
          type: string
          title: Fid
          examples:
          - inst_abc123456
        image_version:
          type: string
          examples:
          - imgver_abc123456
          nullable: true
        status:
          type: string
          const: REFRESHED
          title: Status
      type: object
      required:
      - fid
      - image_version
      - status
      title: RefreshBootDiskResponse
      description: Response model for the refresh-boot-disk endpoint.
  securitySchemes:
    MithrilAPIKey:
      type: http
      scheme: bearer
      bearerFormat: fkey_<key>
x-provenance:
  method: harvested
  publisher: Mithril
  source: https://api.mithril.ai/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)