Vast.ai Serverless API
The Serverless API from Vast.ai — 9 operation(s) for serverless.
OpenAPI Specification
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-Qwen
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vast-ai/refs/heads/main/openapi/vast-ai-serverless-api-openapi.yml