openapi: 3.1.0
info:
  title: Vast.ai Accounts Serverless 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: Serverless
paths:
  /api/v0/workergroups/:
    post:
      summary: create workergroup
      description: 'Creates a new workergroup configuration that manages worker instances for a serverless endpoint.


        CLI Usage: vast-ai create workergroup --template_hash <HASH> --endpoint_name <NAME> [options]'
      security:
      - BearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                endpoint_name:
                  type: string
                  description: Name of the endpoint group
                  example: vLLM-Qwen3-8B
                endpoint_id:
                  type: integer
                  description: ID of existing endpoint group (alternative to endpoint_name)
                  example: 123
                template_hash:
                  type: string
                  description: Hash ID of template to use for worker instances
                  example: abc123def456
                template_id:
                  type: integer
                  description: ID of template (alternative to template_hash)
                  example: 456
                search_params:
                  type: string
                  description: Search query for finding worker instances (alternative to template)
                  default: verified=true rentable=true rented=false
                  example: gpu_name=RTX_3090 rentable=true
                launch_args:
                  type: string
                  description: Additional launch arguments for worker instances
                  example: --env VAR=value
                min_load:
                  type: number
                  description: Minimum load threshold for scaling
                  default: 1.0
                  example: 1.0
                target_util:
                  type: number
                  description: Target GPU utilization
                  default: 0.9
                  example: 0.9
                cold_mult:
                  type: number
                  description: Cold start multiplier
                  default: 3.0
                  example: 3.0
                cold_workers:
                  type: integer
                  description: Number of cold workers to maintain
                  default: 3
                  example: 3
                max_workers:
                  type: integer
                  description: Maximum number of worker instances
                  default: 20
                  example: 20
                test_workers:
                  type: integer
                  description: Number of test workers
                  default: 3
                  example: 3
                gpu_ram:
                  type: integer
                  description: Minimum GPU RAM in GB
                  default: 24
                  example: 24
      responses:
        '200':
          description: Successfully created workergroup
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  id:
                    type: integer
                    description: ID of created autoscaling job
                    example: 789
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    enum:
                    - invalid_args
                  msg:
                    type: string
                    example: Please assign your workergroup to a valid endpoint identifier
        '401':
          description: Unauthorized
          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=4.0
      tags:
      - Serverless
    get:
      summary: show workergroup
      description: 'Retrieves the list of workergroups associated with the authenticated user.


        CLI Usage: vastai show workergroups'
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 123
                        min_load:
                          type: number
                          example: 1.0
                        target_util:
                          type: number
                          example: 0.9
                        cold_mult:
                          type: number
                          example: 3.0
                        test_workers:
                          type: integer
                          example: 3
                        template_hash:
                          type: string
                          example: abc123def456
                        template_id:
                          type: integer
                          example: 456
                        search_query:
                          type: object
                          description: Parsed search parameters as JSON object
                          example: verified=true rentable=true rented=false
                        launch_args:
                          type: string
                          example: --env VAR=value
                        gpu_ram:
                          type: number
                          example: 24
                        endpoint_name:
                          type: string
                          example: my_endpoint
                        endpoint_id:
                          type: integer
                          example: 789
                        api_key:
                          type: string
                          example: your_api_key_here
                        created_at:
                          type: string
                          format: date-time
                          example: '2023-10-01T12:00:00Z'
                        user_id:
                          type: integer
                          example: 456
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                  msg:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                  msg:
                    type: string
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: API requests too frequent endpoint threshold=2.0
      tags:
      - Serverless
  /api/v0/endptjobs/:
    post:
      summary: create endpoint
      description: 'This endpoint creates a new job processing endpoint with specified parameters.


        CLI Usage: vast-ai create endpoint'
      security:
      - BearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                min_load:
                  type: number
                  description: Minimum load for the endpoint.
                  default: 10.0
                  example: 50.0
                target_util:
                  type: number
                  description: Target utilization for the endpoint.
                  default: 0.9
                  example: 0.75
                cold_mult:
                  type: number
                  description: Multiplier for cold start.
                  default: 2.5
                  example: 2.0
                cold_workers:
                  type: integer
                  description: Number of cold workers.
                  default: 5
                  example: 5
                max_workers:
                  type: integer
                  description: Maximum number of workers.
                  default: 20
                  example: 20
                endpoint_name:
                  type: string
                  description: Name of the endpoint.
                  default: default-endpoint
                  example: my_endpoint
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  result:
                    type: integer
                    description: The ID of the created endpoint
                    example: 12345
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Error'
                  properties:
                    error:
                      type: string
                      enum:
                      - invalid_args
        '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=4.0
      tags:
      - Serverless
    get:
      summary: show endpoints
      description: Retrieve a list of endpoint jobs for the authenticated user.
      security:
      - BearerAuth: []
      responses:
        '200':
          description: A list of endpoint jobs
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 123
                        min_load:
                          type: number
                          example: 0.0
                        target_util:
                          type: number
                          example: 0.9
                        cold_mult:
                          type: number
                          example: 2.5
                        cold_workers:
                          type: integer
                          example: 5
                        max_workers:
                          type: integer
                          example: 20
                        endpoint_name:
                          type: string
                          example: vLLM-Qwen3-8B
                        api_key:
                          type: string
                          example: your_api_key_here
                        user_id:
                          type: integer
                          example: 456
                        created_at:
                          type: string
                          format: date-time
                          example: '2023-10-01T12:00:00Z'
                        endpoint_state:
                          type: string
                          example: active
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: invalid_args
                  msg:
                    type: string
                    example: No endpoints for user found
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                  msg:
                    type: string
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: API requests too frequent endpoint threshold=3.0
      tags:
      - Serverless
  /api/v0/workergroups/{id}/:
    delete:
      summary: delete workergroup
      description: 'Deletes an existing workergroup.


        CLI Usage: vastai delete workergroup <ID>'
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the workergroup to delete
        schema:
          type: integer
          example: 4242
      responses:
        '200':
          description: Workergroup deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  deleted_workers:
                    type: array
                    description: List of worker instances that were deleted
                    items:
                      type: integer
                    example:
                    - 1001
                    - 1002
                  failed_workers:
                    type: array
                    description: List of worker instances that failed to delete
                    items:
                      type: integer
                    example: []
                  msg:
                    type: string
                    description: Additional information about the deletion
                    example: Deleted workergroup and 2 workers
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: invalid_args
                  msg:
                    type: string
                    example: Invalid autojob ID
        '404':
          description: Workergroup not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: no_such_workergroup
                  msg:
                    type: string
                    example: No workergroup by that id is available.
                  id:
                    type: integer
                    example: 4242
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                  msg:
                    type: string
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: API requests too frequent endpoint threshold=3.0
      tags:
      - Serverless
    put:
      summary: update workergroup
      description: 'Updates the properties of an existing workergroup based on the provided parameters.


        CLI Usage: vastai update workergroup <ID> [OPTIONS]'
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the workergroup to update.
        schema:
          type: integer
          example: 4242
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                min_load:
                  type: number
                  description: Minimum load for the workergroup.
                  example: 1.0
                target_util:
                  type: number
                  description: Target utilization for the workergroup.
                  example: 0.9
                cold_mult:
                  type: number
                  description: Cold multiplier for the workergroup.
                  example: 3.0
                test_workers:
                  type: integer
                  description: Number of test workers for performance estimation.
                  default: 3
                  example: 3
                template_hash:
                  type: string
                  description: Template hash for the workergroup.
                  example: abc123def456
                template_id:
                  type: integer
                  description: Template ID for the workergroup.
                  example: 456
                search_params:
                  type: string
                  description: Search parameters for offers (JSON object or query string).
                  default: verified=true rentable=true rented=false
                  example: gpu_name=RTX_3090 rentable=true
                launch_args:
                  type: string
                  description: Launch arguments for creating instances.
                  example: --env VAR=value
                gpu_ram:
                  type: number
                  description: Estimated GPU RAM requirement.
                  example: 24
                endpoint_name:
                  type: string
                  description: Deployment endpoint name.
                  example: vLLM-Qwen3-8B
                endpoint_id:
                  type: integer
                  description: Deployment endpoint ID.
                  example: 123
      responses:
        '200':
          description: Successfully updated the workergroup.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: invalid_args
                  msg:
                    type: string
                    example: Workgroup not found for user
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                  msg:
                    type: string
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: API requests too frequent endpoint threshold=2.0
      tags:
      - Serverless
  /api/v0/endptjobs/{id}/:
    delete:
      summary: delete endpoint
      description: 'Deletes an endpoint group by ID. Associated workergroups will also be deleted.


        CLI Usage: vastai delete endpoint <ID>'
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the endpoint group to delete
        schema:
          type: integer
          example: 4242
      responses:
        '200':
          description: Endpoint group successfully deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  deleted_workers:
                    type: array
                    description: List of worker instances that were deleted (if any)
                    items:
                      type: integer
                    example:
                    - 1001
                    - 1002
                  failed_workers:
                    type: array
                    description: List of worker instances that failed to delete (if any)
                    items:
                      type: integer
                    example: []
                  msg:
                    type: string
                    description: Additional information about the deletion
                    example: Deleted endpoint job and 2 workers
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: invalid_args
                  msg:
                    type: string
                    example: Routegroup not found for user
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                  msg:
                    type: string
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: API requests too frequent endpoint threshold=3.0
      tags:
      - Serverless
    put:
      summary: update endpoint
      description: 'Updates the specified endpoint group with the provided parameters.


        CLI Usage: vastai update endpoint ID [OPTIONS]'
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the endpoint group to update
        schema:
          type: integer
          example: 4242
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                min_load:
                  type: number
                  description: Minimum floor load in perf units/s (token/s for LLMs)
                  example: 0.0
                target_util:
                  type: number
                  description: Target capacity utilization (fraction, max 1.0)
                  example: 0.9
                cold_mult:
                  type: number
                  description: Cold/stopped instance capacity target as multiple of hot capacity target
                  example: 2.5
                cold_workers:
                  type: integer
                  description: Min number of workers to keep 'cold' when you have no load
                  example: 5
                max_workers:
                  type: integer
                  description: Max number of workers your endpoint group can have
                  example: 20
                endpoint_name:
                  type: string
                  description: Deployment endpoint name
                  example: my_endpoint
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: invalid_args
                  msg:
                    type: string
                    example: Endpointgroup not found for user
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                  msg:
                    type: string
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: API requests too frequent endpoint threshold=2.0
      tags:
      - Serverless
  /get_workergroup_logs/:
    post:
      servers:
      - url: https://run.vast.ai
        description: Production server
      summary: get workergroup logs
      description: Retrieves logs for a specific workergroup by ID.
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: ID of the worker group
                  default: 12345
                  example: 12345
                  minimum: 1
                tail:
                  type: integer
                  description: Number of log lines to retrieve from the end
                  default: 10000
                  example: 1000
                  minimum: 1
      responses:
        '200':
          description: Logs successfully retrieved.
          content:
            application/json:
              schema:
                oneOf:
                - title: Success - Logs Retrieved
                  type: object
                  properties:
                    logs:
                      type: string
                      description: The workergroup logs
                      example: '2023-10-01 12:00:00 - Workergroup started

                        2023-10-01 12:01:00 - Instance scaled up'
                - title: Error Response
                  type: string
                  description: Error message when workergroup not found or authentication fails
                  example: 'authenticate_workergroup_apikey: invalid api_key or workergroup 12345 not found'
      tags:
      - Serverless
  /get_workergroup_workers/:
    post:
      servers:
      - url: https://run.vast.ai
        description: Production server
      summary: get workergroup workers
      description: 'Retrieves the current list and status of workers for a specific workergroup.


        Useful for monitoring, debugging connectivity issues, and understanding resource usage within a workergroup.'
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: ID of the workergroup to monitor
                  default: 12345
                  example: 12345
                  minimum: 1
      responses:
        '200':
          description: Workers successfully retrieved.
          content:
            application/json:
              schema:
                oneOf:
                - title: Success - Workers Retrieved
                  type: object
                  properties:
                    workers:
                      type: array
                      description: List of workers in this workergroup
                      items:
                        type: object
                        properties:
                          id:
                            type: integer
                            description: Workergroup instance ID
                            example: 67890
                          status:
                            type: string
                            description: Current worker status
                            example: running
                          url:
                            type: string
                            description: Worker instance URL
                            example: http://192.168.1.10:8000
                          created_at:
                            type: string
                            description: When the worker was created
                            example: '2023-10-01T12:00:00Z'
                - title: Error Response
                  type: string
                  description: Error message when workergroup not found or authentication fails
                  example: 'authenticate_workergroup_apikey: invalid api_key or workergroup 12345 not found'
      tags:
      - Serverless
  /get_endpoint_logs/:
    post:
      servers:
      - url: https://run.vast.ai
        description: Production server
      summary: get endpoint logs
      description: Retrieves logs for a specific endpoint by name.
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - endpoint
              properties:
                endpoint:
                  type: string
                  description: Name of the endpoint
                  example: vLLM-Qwen3-8B
                tail:
                  type: integer
                  description: Number of log lines to retrieve from the end
                  default: 10000
                  example: 1000
      responses:
        '200':
          description: Successfully retrieved endpoint logs.
          content:
            application/json:
              schema:
                oneOf:
                - title: Success - Logs Retrieved
                  type: object
                  properties:
                    logs:
                      type: string
                      description: The endpoint logs
                      example: '2023-10-01 12:00:00 - Worker started

                        2023-10-01 12:01:00 - Request processed'
                - title: Error Response
                  type: string
                  description: Error message when endpoint not found or authentication fails
                  example: 'authenticate_endpoint_apikey: invalid api_key or endpoint vLLM-Qwen3-8B not found'
      tags:
      - Serverless
  /get_endpoint_workers/:
    post:
      servers:
      - url: https://run.vast.ai
        description: Production server
      summary: get endpoint workers
      description: 'Retrieves the current list and status of workers for a specific endpoint.


        Useful for monitoring, debugging connectivity issues, and understanding resource usage.'
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: ID of the endpoint to monitor
                  default: 12345
                  example: 12345
                  minimum: 1
      responses:
        '200':
          description: Successfully retrieved endpoints workers.
          content:
            application/json:
              schema:
                oneOf:
                - title: Success - Workers Retrieved
                  type: object
                  properties:
                    workers:
                      type: array
                      description: List of workers for this endpoint
                      items:
                        type: object
                        properties:
                          id:
                            type: integer
                            description: Worker instance ID
                            example: 67890
                          status:
                            type: string
                            description: Current worker status
                            example: running
                          url:
                            type: string
                            description: Worker instance URL
                            example: http://192.168.1.10:8000
                          created_at:
                            type: string
                            description: When the worker was created
                            example: '2023-10-01T12:00:00Z'
                - title: Error Response
                  type: string
                  description: Error message when endpoint not found or authentication fails
                  example: 'authenticate_endpoint_apikey: invalid api_key or endpoint vLLM-Qwen3-8B not found'
      tags:
      - Serverless
  /route/:
    post:
      servers:
      - url: https://run.vast.ai
        description: Production server
      summary: route
      description: 'Calls on the serverless engine to retrieve a GPU instance address within your endpoint for processing a request.


        The engine will return either a ready worker URL or status information if no workers are available.'
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - endpoint
              - cost
              properties:
                endpoint:
                  type: string
                  description: Name of the endpoint
                  example: vLLM-Qwen3-8B
                cost:
                  type: number
                  format: float
                  description: The estimated compute resources for the request
                  default: 100.0
                  example: 242.0
                  minimum: 0
      responses:
        '200':
          description: Success response - either worker assignment or status
          content:
            application/json:
              schema:
                oneOf:
                - title: Worker Available
                  type: object
                  properties:
                    endpoint:
                      type: string
                      description: Same as the input parameter
                      example: vLLM-Qwen3-8B
                    url:
                      type: string
                      description: The address of the worker instance to send the request to
                      example: http://192.168.1.10:8000
                    cost:
                      type: number
                      description: Same as the input parameter
                      example: 242.0
                    reqnum:
                      type: integer
                      description: Request number corresponding to this worker instance
                      example: 12345
                    signature:
                      type: string
                      description: Cryptographic signature authenticating the response
                      example: a1b2c3d4e5f60708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20
                    __request_id:
                      type: string
                      description: Unique identifier generated by the server for this request
                      example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                - title: No Worker Available
                  type: object
                  properties:
                    endpoint:
                      type: string
                      description: Same as the input parameter
                      example: vLLM-Qwen3-8B
                    status:
                      type: string
                      description: Breakdown of workers in your endpoint group by status
                      example: Stopped
                    __request_id:
                      type: string
                      description: Unique identifier generated by the server for this request
                      example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
        '401':
          description: Unauthorized - authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Authentication failed
        '400':
          description: Bad Request - invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid endpoint or missing required parameters
      tags:
      - Serverless
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