Vast.ai Machines API

openapi: 3.1.0
info:
  title: Vast.ai Accounts Machines API
  description: API for managing cloud GPU instances, volumes, and resources on Vast.ai
  version: 1.0.0
  contact:
    name: Vast.ai Support
    url: https://discord.gg/hSuEbSQ4X8
servers:
- url: https://console.vast.ai
  description: Production API server
security:
- bearerAuth: []
tags:
- name: Machines
paths:
  /api/v0/machines/{machine_id}/cancel_maint:
    put:
      summary: cancel maint
      description: Cancel a scheduled maintenance window for a specified machine.
      parameters:
      - name: machine_id
        in: path
        required: true
        description: ID of the machine to cancel maintenance for.
        schema:
          type: integer
      responses:
        '200':
          description: Maintenance window successfully canceled.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  ctime:
                    type: number
                    format: float
                    description: Current time in seconds since the epoch.
                  machine_id:
                    type: integer
                    description: ID of the machine.
                  msg:
                    type: string
                    example: deleted 1 scheduled maintenance window(s) on machine 1234
        '404':
          description: Machine not found or does not belong to the user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  msg:
                    type: string
                    example: No such machine id
                  machine_id:
                    type: integer
                  user_id:
                    type: integer
      security:
      - BearerAuth: []
      tags:
      - Machines
  /api/v0/machines/{machine_id}/cleanup:
    put:
      summary: cleanup machine
      description: 'This endpoint removes expired contracts on a specified machine, freeing up space.


        CLI Usage: vast-ai cleanup machine {machine_id}'
      security:
      - BearerAuth: []
      parameters:
      - name: machine_id
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the machine to clean up.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: An empty JSON object is expected.
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  ctime:
                    type: number
                    format: float
                    example: 1633036800.0
                  machine_id:
                    type: integer
                    example: 123
                  user_id:
                    type: integer
                    example: 456
                  num_deleted:
                    type: integer
                    example: 5
                  msg:
                    type: string
                    example: deleted 5 expired contracts on machine 123
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: API requests too frequent endpoint threshold=8
      tags:
      - Machines
  /api/v0/machines/create_asks/:
    put:
      summary: list machine
      description: 'Creates or updates ask contracts for a machine to list it for rent on the vast.ai platform.

        Allows setting pricing, minimum GPU requirements, end date and discount rates.


        CLI Usage: vast list machine <machine_id> [options]'
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - machine
              properties:
                machine:
                  type: integer
                  description: ID of the machine to list
                price_gpu:
                  type: number
                  format: float
                  description: Price per GPU per hour
                price_disk:
                  type: number
                  format: float
                  description: Price per GB of disk storage
                price_inetu:
                  type: number
                  format: float
                  description: Price per GB of upload bandwidth
                price_inetd:
                  type: number
                  format: float
                  description: Price per GB of download bandwidth
                price_min_bid:
                  type: number
                  format: float
                  description: Minimum bid price allowed
                min_chunk:
                  type: integer
                  description: Minimum number of GPUs that must be rented together
                  default: 1
                end_date:
                  type: number
                  format: float
                  description: Unix timestamp for when the listing expires
                credit_discount_max:
                  type: number
                  format: float
                  description: Maximum discount rate allowed for prepaid credits
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  extended:
                    type: integer
                    description: Number of client contracts extended to new end date
                  msg:
                    type: string
                    description: Status message if success is false
                example:
                  success: true
                  extended: 2
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: invalid_args
                  msg:
                    type: string
                    example: Invalid machine id or parameters
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: not_authorized
                  msg:
                    type: string
                    example: Only machine owner can create ask contracts
      tags:
      - Machines
  /api/v0/machines/{machine_id}/defjob:
    delete:
      summary: remove defjob
      description: 'Deletes the default job (background instances) for a specified machine.


        CLI Usage: vast-ai remove defjob {machine_id}'
      security:
      - BearerAuth: []
      parameters:
      - name: machine_id
        in: path
        required: true
        description: ID of the machine to remove the default job from.
        schema:
          type: integer
          example: 12345
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  machine_id:
                    type: integer
                    example: 12345
                  user_id:
                    type: integer
                    example: 67890
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: API requests too frequent endpoint threshold=1.2
      tags:
      - Machines
  /api/v0/machines/{machine_id}/reports:
    get:
      summary: show reports
      description: 'Retrieves a list of the most recent reports for a given machine. Each report includes details such as the problem identified, a message describing the issue, and the timestamp when the report was created.


        CLI Usage: vastai reports <machine_id>'
      security:
      - BearerAuth: []
      parameters:
      - name: machine_id
        in: path
        required: true
        schema:
          type: integer
        description: The unique identifier of the machine.
      responses:
        '200':
          description: An array of reports for the specified machine.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    problem:
                      type: string
                      description: The type of problem reported.
                    message:
                      type: string
                      description: Detailed message describing the problem.
                    created_at:
                      type: string
                      format: date-time
                      description: Timestamp when the report was created.
        '404':
          description: Machine not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Machines
  /api/v0/machines/{machine_id}/dnotify:
    put:
      summary: schedule maint
      description: 'Schedules a maintenance window for a specified machine and notifies clients.


        CLI Usage: vast-ai schedule maint {machine_id} --sdate {sdate} --duration {duration}'
      security:
      - BearerAuth: []
      parameters:
      - name: machine_id
        in: path
        required: true
        description: ID of the machine to schedule maintenance for.
        schema:
          type: integer
          example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - sdate
              - duration
              properties:
                sdate:
                  type: string
                  format: date-time
                  description: Start date and time of the maintenance window.
                  example: '2023-10-30T14:00:00Z'
                duration:
                  type: integer
                  description: Duration of the maintenance window in hours.
                  example: 2
                maintenance_reason:
                  type: string
                  description: Reason for the maintenance.
                  example: Routine hardware check
                maintenance_category:
                  type: string
                  description: Category of the maintenance.
                  enum:
                  - power
                  - internet
                  - disk
                  - gpu
                  - software
                  - other
                  example: software
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  you_sent:
                    type: string
                    example: 2 notifications sent
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: API requests too frequent endpoint threshold=2.5
      tags:
      - Machines
  /api/v0/machines/create_bids/:
    put:
      summary: set defjob
      description: 'Creates default jobs (background instances) for a specified machine with the given parameters.


        CLI Usage: vast set defjob {machine_id} --price_gpu {price} --price_inetu {price} --price_inetd {price} --image {image} [--args {args}]'
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - machine
              - price_gpu
              - price_inetu
              - price_inetd
              - image
              properties:
                machine:
                  type: integer
                  description: ID of the machine to create jobs for.
                  example: 12345
                price_gpu:
                  type: number
                  format: float
                  description: Price per GPU per day.
                  example: 0.5
                price_inetu:
                  type: number
                  format: float
                  description: Price for internet upload.
                  example: 0.1
                price_inetd:
                  type: number
                  format: float
                  description: Price for internet download.
                  example: 0.1
                image:
                  type: string
                  description: Docker image to use for the job.
                  example: vastai/tensorflow
                args:
                  type: array
                  items:
                    type: string
                  description: Arguments for the Docker image.
                  example:
                  - --arg1
                  - --arg2
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  machine_id:
                    type: integer
                    example: 12345
                  user_id:
                    type: integer
                    example: 67890
                  you_sent:
                    type: object
                    description: The original request JSON.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: API requests too frequent endpoint threshold=2.8
      tags:
      - Machines
  /api/v0/machines/{machine_id}/minbid:
    put:
      summary: set min-bid
      description: 'Sets the minimum bid price for a specified machine.


        CLI Usage: vast set min-bid {machine_id} --price {price}'
      security:
      - BearerAuth: []
      parameters:
      - name: machine_id
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the machine.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - price
              properties:
                price:
                  type: number
                  format: float
                  description: Minimum bid price for the machine.
                  example: 0.5
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  you_sent:
                    type: object
                    description: The original request JSON.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: API requests too frequent endpoint threshold=1.5
      tags:
      - Machines
  /api/v0/machines/:
    get:
      summary: show machines
      description: Fetches data for multiple machines associated with the authenticated user.
      operationId: getMachines
      parameters:
      - name: user_id
        in: query
        required: true
        description: The ID of the user whose machines are being requested.
        schema:
          type: string
      responses:
        '200':
          description: A list of machines
          content:
            application/json:
              schema:
                type: object
                properties:
                  machines:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The unique identifier for the machine.
                        name:
                          type: string
                          description: The name of the machine.
        '401':
          description: Unauthorized - User authentication failed
        '429':
          description: Too Many Requests - Rate limit exceeded
      security:
      - BearerAuth: []
      tags:
      - Machines
  /api/v0/machines/{machine_id}/asks:
    delete:
      summary: unlist machine
      description: 'Removes all ''ask'' type offer contracts for a specified machine, effectively unlisting it from being available for rent.


        CLI Usage: vastai unlist machine <id>'
      security:
      - BearerAuth: []
      parameters:
      - name: machine_id
        in: path
        required: true
        description: The ID of the machine to unlist.
        schema:
          type: integer
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  machine_id:
                    type: integer
                    example: 123
                  user_id:
                    type: integer
                    example: 456
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: API requests too frequent endpoint threshold=1.8
      tags:
      - Machines
components:
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
        msg:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key
      description: API key must be provided as a query parameter