Sign in

v1

latestOpenAPI 3.1.02026-07-13897404.3 KB
Instances

create instance

Creates a new instance by accepting an "ask" contract from a provider.

  • Use the search offers endpoint to discover available machines.
  • If template_id is provided, those template defaults are either merged or overridden by parameters specified in the request body.

Template Precedence Rules:

  • Scalar fields (image, disk, runtype, etc.): Request value overrides template value
  • env: Merged by key. Request values win on key conflicts
  • extra_filters: Merged by key. Request values win on key conflicts

For detailed template usage, see Creating and Using Templates with API.

CLI Usage: vastai create instance <offer_id> <image> [options]

put/api/v0/asks/{id}/

Path parameters

idinteger required

ID of the offer to accept (ask_id)

Request body

imagestring required

Docker image to use for the instance.

template_hash_idstring

Content-based hash ID of a template to use as base configuration. Template values are merged with or overridden by request parameters (see precedence rules in endpoint description). When using a template, the image field is optional as the template provides it.

Example: 4e17788f74f075dd9aab7d0d4427968f

labelstring

Custom name for the instance

disknumber float

Size of local disk partition (in GB)

runtype'ssh' | 'jupyter' | 'args' | 'ssh_proxy' | 'ssh_direct' | 'jupyter_proxy' | 'jupyter_direct'

Launch mode for the instance. If omitted, defaults to 'ssh' unless args/args_str is provided.

target_state'running' | 'stopped'

Desired initial state of the instance

pricenumber

Bid price per machine (in $/hour). Only for interruptible instances

envstring

Environment variables and port mappings in Docker flag format. When using a template, request env is merged with template env - existing keys are retained, new keys are appended, conflicting keys use the request value.

Example: "-e HF_TOKEN=hf_xxx123456789 -e MODEL_ID=TheBloke/Llama-2-7B-Chat-GPTQ -p 8000:8000"

cancel_unavailboolean

Whether to cancel if instance cannot start immediately. Defaults to false for interruptibles. Defaults to true for on-demand with target_state='running'

vmboolean

Whether this is a VM instance

onstartstring

Commands to run when instance starts

Example : env | grep _ >> /etc/environment; echo 'starting up'

argsstring[]

Arguments array to passed to the image entrypoint

Example : ["bash", "-c", "env | grep _ >> /etc/environment; echo 'starting up'"]

args_strstring

Arguments string to pass to the entrypoint (alternative to args)

Example : args_str: bash -c "env | grep _ >> /etc/environment; echo 'starting up'"

use_jupyter_labboolean

Launch instance with jupyter lab instead of notebook

jupyter_dirstring

Directory to launch Jupyter from

Example : /home/notebooks

python_utf8boolean

Set python's locale to C.UTF-8

lang_utf8boolean

Set locale to C.UTF-8

forceboolean

Skip sanity checks when creating from an existing instance

userstring

User to use with docker create (breaks some images, use with caution)

image_loginstring

Docker registry credentials if needed

Response

Instance created successfully

successboolean

If the instance was created successfully

new_contractinteger

ID of the newly created instance contract

Example response

{
  "success": true,
  "new_contract": 1234568
}