Vast.ai Instances API
The Instances API from Vast.ai — 14 operation(s) for instances.
OpenAPI Specification
openapi: 3.1.0
info:
title: Vast.ai Accounts Instances 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: Instances
paths:
/api/v0/instances/{id}/ssh/:
post:
summary: attach ssh-key
description: 'Attaches an SSH key to the specified instance, allowing SSH access using the provided key.
CLI Usage: vast attach instance_id ssh_key'
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: ID of the instance to attach the SSH key to
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ssh_key:
type: string
description: The SSH key to attach to the instance
example: ssh-rsa AAAAB3NzaC1yc2EAAA...
responses:
'200':
description: SSH key attached successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
msg:
type: string
example: SSH key attached successfully
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Instances
/api/v0/commands/copy_direct/:
delete:
summary: cancel copy
description: Cancel a remote copy operation specified by the destination ID (dst_id).
operationId: cancelRemoteRsync
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
dst_id:
type: string
description: ID of the copy instance target to cancel.
required:
- dst_id
responses:
'200':
description: Remote copy canceled successfully.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
'400':
description: Invalid arguments provided.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: invalid_args
msg:
type: string
example: Invalid dst_id.
'404':
description: Destination ID not found or access denied.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: no_such_user
msg:
type: string
example: No such user.
security:
- BearerAuth: []
x-rateLimit: 3.5
tags:
- Instances
put:
summary: copy
description: Initiate a remote copy operation to transfer data from one instance to another or between an instance and the local machine.
operationId: initiateRemoteRsync
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
src_id:
type: string
description: ID of the source instance.
dst_id:
type: string
description: ID of the destination instance.
src_path:
type: string
description: Path of the source data.
dst_path:
type: string
description: Path of the destination data.
required:
- src_path
- dst_path
responses:
'200':
description: Remote copy initiated successfully.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
msg:
type: string
example: Remote to Remote copy initiated - check instance status bar for progress updates (~30 seconds delayed).
'400':
description: Invalid arguments provided.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: invalid_args
msg:
type: string
example: Invalid src_path.
'404':
description: Source or destination ID not found or access denied.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: no_such_user
msg:
type: string
example: No such user.
security:
- BearerAuth: []
x-rateLimit: 3.5
tags:
- Instances
/api/v0/commands/rclone/:
delete:
summary: cancel sync
description: 'Cancels an in-progress remote sync operation identified by the destination instance ID.
This operation cannot be resumed once canceled and must be restarted if needed.'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
dst_id:
type: integer
description: The destination instance ID of the sync operation to cancel.
required:
- dst_id
responses:
'200':
description: Sync operation canceled successfully.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
msg:
type: string
example: Remote copy canceled - check instance status bar for progress updates (~30 seconds delayed).
'400':
description: Invalid request due to missing or incorrect parameters.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: invalid_args
msg:
type: string
example: Invalid dst_id.
'404':
description: Instance not found.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: no_such_instance
msg:
type: string
example: No such instance.
tags:
- Instances
post:
summary: cloud copy
description: Starts a cloud copy operation by sending a command to the remote server. The operation can transfer data between an instance and a cloud service.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
instance_id:
type: string
description: ID of the instance.
src:
type: string
description: Source path for the copy operation.
dst:
type: string
description: Destination path for the copy operation.
selected:
type: string
description: ID of the cloud connection.
transfer:
type: string
description: Type of transfer (e.g., "Instance To Cloud" or "Cloud To Instance").
flags:
type: array
items:
type: string
description: Additional flags for the operation.
api_key:
type: string
description: API key for authentication.
responses:
'200':
description: Cloud copy operation initiated successfully.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
msg:
type: string
result_url:
type: string
'400':
description: Bad request due to invalid parameters or cloud service.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
msg:
type: string
security:
- BearerAuth: []
tags:
- Instances
/api/v0/instances/bid_price/{id}/:
put:
summary: change bid
description: 'Change the current bid price of an instance to a specified price.
CLI Usage: vastai change bid id [--price PRICE]'
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: Instance ID
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- client_id
- price
properties:
client_id:
type: string
description: Client identifier (usually "me")
example: me
price:
type: number
description: Bid price in $/hour
minimum: 0.001
maximum: 32.0
example: 0.17
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
enum:
- invalid_args
msg:
type: string
example: Please set a bid price >= 0.001.
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
enum:
- no_such_instance
msg:
type: string
example: Instance with that ID does not exist.
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: API requests too frequent endpoint threshold=5.5
tags:
- Instances
/api/v0/asks/{id}/:
put:
summary: create instance
description: 'Creates a new instance by accepting an "ask" contract from a provider. This is the main endpoint for launching new instances on Vast.ai.
CLI Usage: vast create instance <offer_id> [options]'
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: ID of the offer to accept
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
template_id:
type: integer
description: Optional template ID to use for instance configuration
example: 89
template_hash_id:
type: string
description: Optional template hash ID to use for instance configuration
example: abc123def456
image:
type: string
description: Docker image to use for the instance
example: tensorflow/tensorflow:latest-gpu
maxLength: 1024
disk:
type: number
description: Storage space in GB
minimum: 8.0
default: 10.0
example: 32.0
env:
type: object
description: Environment variables and port mappings
example:
JUPYTER_TOKEN: abc123
PORTAL_CONFIG: '{"ports": [8080, 8081]}'
maxLength: 256
runtype:
type: string
description: Instance run type
enum:
- ssh
- jupyter
- args
- ssh_proxy
- ssh_direct
- jupyter_proxy
- jupyter_direct
example: jupyter
onstart:
type: string
description: Commands to run when instance starts
maxLength: 4096
example: pip install -r requirements.txt
label:
type: string
description: User-defined label for the instance
maxLength: 256
example: training-job-1
image_login:
type: string
description: Docker registry credentials if needed
example: -u username -p password docker.io
price:
type: number
description: Bid price per hour for interruptible instances
minimum: 0.001
maximum: 128.0
example: 0.4
target_state:
type: string
description: Desired initial state of the instance
enum:
- running
- stopped
default: running
example: running
cancel_unavail:
type: boolean
description: Whether to cancel if instance cannot start immediately. Defaults to false for interruptibles, true for on-demand with target_state='running'
example: true
vm:
type: boolean
description: Whether this is a VM instance
default: false
client_id:
type: string
description: Client identifier (usually "me")
example: me
apikey_id:
type: string
description: Optional API key identifier for audit logging
args:
type: array
items:
type: string
description: Arguments to pass to the container entrypoint
example:
- -c
- echo hello; sleep infinity;
entrypoint:
type: string
description: Override entrypoint for args launch instance
example: bash
use_ssh:
type: boolean
description: Launch as an SSH instance type (deprecated, use runtype instead)
python_utf8:
type: boolean
description: Set python's locale to C.UTF-8
lang_utf8:
type: boolean
description: Install and generate locales before instance launch, set locale to C.UTF-8
use_jupyter_lab:
type: boolean
description: Launch instance with jupyter lab instead of notebook
jupyter_dir:
type: string
description: Directory in instance to use to launch jupyter
force:
type: boolean
description: Skip sanity checks when creating from an existing instance
user:
type: string
description: User to use with docker create (breaks some images, use with caution)
volume_info:
type: object
description: Volume creation/linking information
properties:
create_new:
type: boolean
description: Whether to create a new volume
volume_id:
type: integer
description: ID of existing volume to link or volume offer ID for new volume
size:
type: integer
description: Size of the volume in GB (for new volumes)
mount_path:
type: string
description: Mount path for the volume inside the container
name:
type: string
description: Label for the new volume
responses:
'200':
description: Instance created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
new_contract:
type: integer
description: ID of the newly created instance contract
example: 1234568
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
enum:
- invalid_args
- invalid_price
- no_ssh_key_for_vm
msg:
type: string
example: 'error 400/3467: Invalid args: ''id'' is required and must be a valid offer ID'
ask_id:
type: integer
example: 1234567
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: invalid_args
msg:
type: string
example: 'error 403/3586: Offer 1234567 is not your own. Hosts can only rent their own machines.'
ask_id:
type: integer
example: 1234567
'404':
description: Offer not found or not available
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: invalid_args
msg:
type: string
example: 'error 404/3603: no_such_ask Instance type by id 1234567 is not available.'
ask_id:
type: integer
example: 1234567
'410':
description: Offer no longer available (when cancel_unavail is true and instance cannot start)
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: no_such_ask
msg:
type: string
example: 'error 410/3907: no_such_ask Instance type 1234567 is no longer available.'
ask_id:
type: integer
example: 1234567
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: API requests too frequent endpoint threshold=4.5
tags:
- Instances
/api/v0/instances/{id}/:
delete:
summary: destroy instance
description: 'Destroys/deletes an instance permanently. This is irreversible and will delete all data.
CLI Usage: vast-ai destroy instance <id>
Example: vast-ai destroy instance 4242'
parameters:
- in: path
name: id
required: true
schema:
type: integer
description: ID of the instance to destroy
example: 4242
responses:
'200':
description: Instance destroyed successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
description: Whether the destruction was successful
msg:
type: string
description: Optional status message
example: Instance destroyed successfully
'400':
description: Bad request - invalid instance ID
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: invalid_args
msg:
type: string
example: invalid instance_id
'404':
description: Instance not found
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: not_found
msg:
type: string
example: Instance not found
'429':
description: Too many requests
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: rate_limit_exceeded
msg:
type: string
example: API requests too frequent endpoint threshold=3.0
security:
- BearerAuth: []
tags:
- Instances
put:
summary: manage instance
description: 'Manage instance state and labels. The operation is determined by the request body parameters.
CLI Usage:
- To stop: vastai stop instance <ID>
- To start: vastai start instance <ID>
- To label: vastai label instance <ID> <label>'
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: ID of the instance to modify
example: 1234
requestBody:
required: true
content:
application/json:
schema:
type: object
description: At least one of these parameters should be provided
properties:
state:
type: string
description: Change instance state (optional)
enum:
- stopped
- running
example: stopped
label:
type: string
description: Text label to assign to the instance (optional)
maxLength: 1024
example: My ML Training Job
responses:
'200':
description: Operation completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleBooleanSuccessResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'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.0
tags:
- Instances
get:
summary: show instance
description: 'Retrieves the details of a specific instance for the authenticated user.
This endpoint returns detailed information including SSH connection parameters, instance state, resource utilization, template data, and pricing details.'
security:
- BearerAuth: []
parameters:
- name: id
in: path
description: The ID of the instance to retrieve.
required: true
schema:
type: integer
example: 123
responses:
'200':
description: Success response with instance details.
content:
application/json:
schema:
type: object
properties:
instances:
$ref: '#/components/schemas/Instance'
'400':
description: Bad Request – Invalid instance ID or invalid arguments.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized – Invalid or missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too Many Requests – API requests are too frequent.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: API requests too frequent endpoint threshold=2.0
tags:
- Instances
/api/v0/instances/{id}/ssh/{key}/:
delete:
summary: detach ssh-key
description: 'Detaches an SSH key from a specified instance, removing SSH access for
that key.
CLI Usage: vastai detach <instance_id> <ssh_key_id>
Example: vastai detach 99999 12345'
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
description: ID of the instance to detach the SSH key from
schema:
type: integer
example: 99999
- name: key
in: path
required: true
description: Numeric ID of the SSH key to detach
schema:
type: integer
example: 12345
responses:
'200':
description: SSH key successfully detached
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
msg:
type: string
example: SSH key removed from instance.
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
enum:
- invalid_request
msg:
type: string
example: Invalid request parameters
'404':
description: Instance or SSH key not found
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
enum:
- no_such_instance
- no_such_ssh_key
msg:
type: string
example: Instance not found.
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: API requests too frequent endpoint threshold=2.0
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vast-ai/refs/heads/main/openapi/vast-ai-instances-api-openapi.yml