Skip to main content
POST
/
instances
Create a GPU instance
curl --request POST \
  --url https://runcrate.ai/api/v1/instances \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "gpu_type": "<string>",
  "instance_type_id": "<string>",
  "region": "<string>",
  "gpu_count": 2,
  "cpu_cores": 2,
  "memory": 2,
  "storage": 2,
  "template": "<string>",
  "ssh_key_id": "<string>",
  "env_vars": [
    {
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "startup_commands": [
    "<string>"
  ],
  "storage_id": "<string>",
  "launch_script": "<string>",
  "launch_script_base64": "<string>"
}
'
import requests

url = "https://runcrate.ai/api/v1/instances"

payload = {
    "name": "<string>",
    "gpu_type": "<string>",
    "instance_type_id": "<string>",
    "region": "<string>",
    "gpu_count": 2,
    "cpu_cores": 2,
    "memory": 2,
    "storage": 2,
    "template": "<string>",
    "ssh_key_id": "<string>",
    "env_vars": [
        {
            "key": "<string>",
            "value": "<string>"
        }
    ],
    "startup_commands": ["<string>"],
    "storage_id": "<string>",
    "launch_script": "<string>",
    "launch_script_base64": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    gpu_type: '<string>',
    instance_type_id: '<string>',
    region: '<string>',
    gpu_count: 2,
    cpu_cores: 2,
    memory: 2,
    storage: 2,
    template: '<string>',
    ssh_key_id: '<string>',
    env_vars: [{key: '<string>', value: '<string>'}],
    startup_commands: ['<string>'],
    storage_id: '<string>',
    launch_script: '<string>',
    launch_script_base64: '<string>'
  })
};

fetch('https://runcrate.ai/api/v1/instances', 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://runcrate.ai/api/v1/instances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'gpu_type' => '<string>',
    'instance_type_id' => '<string>',
    'region' => '<string>',
    'gpu_count' => 2,
    'cpu_cores' => 2,
    'memory' => 2,
    'storage' => 2,
    'template' => '<string>',
    'ssh_key_id' => '<string>',
    'env_vars' => [
        [
                'key' => '<string>',
                'value' => '<string>'
        ]
    ],
    'startup_commands' => [
        '<string>'
    ],
    'storage_id' => '<string>',
    'launch_script' => '<string>',
    'launch_script_base64' => '<string>'
  ]),
  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://runcrate.ai/api/v1/instances"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"gpu_type\": \"<string>\",\n  \"instance_type_id\": \"<string>\",\n  \"region\": \"<string>\",\n  \"gpu_count\": 2,\n  \"cpu_cores\": 2,\n  \"memory\": 2,\n  \"storage\": 2,\n  \"template\": \"<string>\",\n  \"ssh_key_id\": \"<string>\",\n  \"env_vars\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"startup_commands\": [\n    \"<string>\"\n  ],\n  \"storage_id\": \"<string>\",\n  \"launch_script\": \"<string>\",\n  \"launch_script_base64\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://runcrate.ai/api/v1/instances")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"gpu_type\": \"<string>\",\n  \"instance_type_id\": \"<string>\",\n  \"region\": \"<string>\",\n  \"gpu_count\": 2,\n  \"cpu_cores\": 2,\n  \"memory\": 2,\n  \"storage\": 2,\n  \"template\": \"<string>\",\n  \"ssh_key_id\": \"<string>\",\n  \"env_vars\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"startup_commands\": [\n    \"<string>\"\n  ],\n  \"storage_id\": \"<string>\",\n  \"launch_script\": \"<string>\",\n  \"launch_script_base64\": \"<string>\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://runcrate.ai/api/v1/instances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"gpu_type\": \"<string>\",\n  \"instance_type_id\": \"<string>\",\n  \"region\": \"<string>\",\n  \"gpu_count\": 2,\n  \"cpu_cores\": 2,\n  \"memory\": 2,\n  \"storage\": 2,\n  \"template\": \"<string>\",\n  \"ssh_key_id\": \"<string>\",\n  \"env_vars\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"startup_commands\": [\n    \"<string>\"\n  ],\n  \"storage_id\": \"<string>\",\n  \"launch_script\": \"<string>\",\n  \"launch_script_base64\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body
{
  "data": {
    "id": "<string>",
    "name": "<string>",
    "gpu_type": "<string>",
    "gpu_count": 123,
    "cpu_cores": 123,
    "memory": 123,
    "storage": 123,
    "region": "<string>",
    "ip": "<string>",
    "os_image": "<string>",
    "cost_per_hour": 123,
    "deployed_at": "2023-11-07T05:31:56Z",
    "created_at": "2023-11-07T05:31:56Z"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

Authorizations

​
Authorization
string
header
required

Use a Runcrate API key with the rc_live_* prefix as the bearer token. Create one at https://www.runcrate.ai/dashboard/api-keys.

Body

application/json

Provide either gpu_type (auto-deploy to cheapest available config) or instance_type_id (specific config from /instances/types).

​
name
string
required

Human-readable instance name.

​
gpu_type
string

GPU model id (e.g. h100-sxm). Required if instance_type_id is not provided.

​
instance_type_id
string

Exact instance-type id from GET /instances/types. Required if gpu_type is not provided.

​
region
string

Region preference. Defaults to auto.

​
gpu_count
integer
Required range: x >= 1
​
cpu_cores
integer
Required range: x >= 1
​
memory
integer

GB

Required range: x >= 1
​
storage
integer

GB ephemeral storage

Required range: x >= 1
​
template
string

Template id to boot from.

​
ssh_key_id
string

ID of an SSH key to inject (create one via POST /ssh-keys).

​
env_vars
object[]

Environment variables to inject. Each item must be { "key": "NAME", "value": "..." }.

​
startup_commands
string[]
​
storage_id
string

Persistent volume to attach at boot. Mounts at /workspace.

​
launch_script
string

Raw shell script to run on boot.

​
launch_script_base64
string

Base64-encoded launch script (alternative to launch_script).

Response

Instance created. Status will be starting or deploying until ready.

​
data
object
required