curl --request PUT \
--url https://console.vast.ai/api/v0/asks/{id}/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"image": "vastai/base-image:@vastai-automatic-tag"
}
'import requests
url = "https://console.vast.ai/api/v0/asks/{id}/"
payload = { "image": "vastai/base-image:@vastai-automatic-tag" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({image: 'vastai/base-image:@vastai-automatic-tag'})
};
fetch('https://console.vast.ai/api/v0/asks/{id}/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://console.vast.ai/api/v0/asks/{id}/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'image' => 'vastai/base-image:@vastai-automatic-tag'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://console.vast.ai/api/v0/asks/{id}/"
payload := strings.NewReader("{\n \"image\": \"vastai/base-image:@vastai-automatic-tag\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://console.vast.ai/api/v0/asks/{id}/")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"image\": \"vastai/base-image:@vastai-automatic-tag\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://console.vast.ai/api/v0/asks/{id}/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"image\": \"vastai/base-image:@vastai-automatic-tag\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"new_contract": 1234568
}{
"success": false,
"error": "invalid_args",
"msg": "error 400/3467: Invalid args: 'id' is required and must be a valid offer ID",
"ask_id": 1234567
}{
"success": false,
"error": "<string>",
"msg": "<string>"
}{
"success": false,
"error": "invalid_args",
"msg": "error 403/3586: Offer 1234567 is not your own. Hosts can only rent their own machines.",
"ask_id": 1234567
}{
"success": false,
"error": "invalid_args",
"msg": "error 404/3603: no_such_ask Instance type by id 1234567 is not available.",
"ask_id": 1234567
}{
"success": false,
"error": "no_such_ask",
"msg": "error 410/3907: no_such_ask Instance type 1234567 is no longer available.",
"ask_id": 1234567
}{
"detail": "API requests too frequent endpoint threshold=4.5"
}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_idis 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 conflictsextra_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]
curl --request PUT \
--url https://console.vast.ai/api/v0/asks/{id}/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"image": "vastai/base-image:@vastai-automatic-tag"
}
'import requests
url = "https://console.vast.ai/api/v0/asks/{id}/"
payload = { "image": "vastai/base-image:@vastai-automatic-tag" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({image: 'vastai/base-image:@vastai-automatic-tag'})
};
fetch('https://console.vast.ai/api/v0/asks/{id}/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://console.vast.ai/api/v0/asks/{id}/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'image' => 'vastai/base-image:@vastai-automatic-tag'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://console.vast.ai/api/v0/asks/{id}/"
payload := strings.NewReader("{\n \"image\": \"vastai/base-image:@vastai-automatic-tag\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://console.vast.ai/api/v0/asks/{id}/")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"image\": \"vastai/base-image:@vastai-automatic-tag\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://console.vast.ai/api/v0/asks/{id}/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"image\": \"vastai/base-image:@vastai-automatic-tag\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"new_contract": 1234568
}{
"success": false,
"error": "invalid_args",
"msg": "error 400/3467: Invalid args: 'id' is required and must be a valid offer ID",
"ask_id": 1234567
}{
"success": false,
"error": "<string>",
"msg": "<string>"
}{
"success": false,
"error": "invalid_args",
"msg": "error 403/3586: Offer 1234567 is not your own. Hosts can only rent their own machines.",
"ask_id": 1234567
}{
"success": false,
"error": "invalid_args",
"msg": "error 404/3603: no_such_ask Instance type by id 1234567 is not available.",
"ask_id": 1234567
}{
"success": false,
"error": "no_such_ask",
"msg": "error 410/3907: no_such_ask Instance type 1234567 is no longer available.",
"ask_id": 1234567
}{
"detail": "API requests too frequent endpoint threshold=4.5"
}Authorizations
API key must be provided in the Authorization header
Path Parameters
ID of the offer to accept (ask_id)
Body
Docker image to use for the instance.
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
Custom name for the instance
Size of local disk partition (in GB)
Launch mode for the instance. If omitted, defaults to 'ssh' unless args/args_str is provided.
ssh, jupyter, args, ssh_proxy, ssh_direct, jupyter_proxy, jupyter_direct Desired initial state of the instance
running, stopped Bid price per machine (in $/hour). Only for interruptible instances
0.001 <= x <= 128Environment 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"
Whether to cancel if instance cannot start immediately. Defaults to false for interruptibles. Defaults to true for on-demand with target_state='running'
Whether this is a VM instance
Commands to run when instance starts
Example : env | grep _ >> /etc/environment; echo 'starting up'
Arguments array to passed to the image entrypoint
Example : ["bash", "-c", "env | grep _ >> /etc/environment; echo 'starting up'"]
Arguments string to pass to the entrypoint (alternative to args)
Example : args_str: bash -c "env | grep _ >> /etc/environment; echo 'starting up'"
Launch instance with jupyter lab instead of notebook
Directory to launch Jupyter from
Example : /home/notebooks
Set python's locale to C.UTF-8
Set locale to C.UTF-8
Skip sanity checks when creating from an existing instance
User to use with docker create (breaks some images, use with caution)
Docker registry credentials if needed
Volume creation/linking information
Show child attributes
Show child attributes