Skip to main content
POST
/
preview
/
v2
/
instances
Create instance
curl --request POST \
  --url https://api.sfcompute.com/preview/v2/instances \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "pool": "<string>",
  "image": "<string>",
  "instance_sku": "isku_k3R-nX9vLm7Qp2Yw5Jd8F",
  "name": "my-resource-name",
  "cloud_init_user_data": "IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=",
  "enable_public_ipv4": true,
  "firewall": "frwl_k3R-nX9vLm7Qp2Yw5Jd8F",
  "tags": {
    "env": "prod",
    "team": "infra"
  },
  "_preview_enable_infiniband": false
}
'
import requests

url = "https://api.sfcompute.com/preview/v2/instances"

payload = {
    "pool": "<string>",
    "image": "<string>",
    "instance_sku": "isku_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "my-resource-name",
    "cloud_init_user_data": "IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=",
    "enable_public_ipv4": True,
    "firewall": "frwl_k3R-nX9vLm7Qp2Yw5Jd8F",
    "tags": {
        "env": "prod",
        "team": "infra"
    },
    "_preview_enable_infiniband": False
}
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({
    pool: '<string>',
    image: '<string>',
    instance_sku: 'isku_k3R-nX9vLm7Qp2Yw5Jd8F',
    name: 'my-resource-name',
    cloud_init_user_data: 'IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=',
    enable_public_ipv4: true,
    firewall: 'frwl_k3R-nX9vLm7Qp2Yw5Jd8F',
    tags: {env: 'prod', team: 'infra'},
    _preview_enable_infiniband: false
  })
};

fetch('https://api.sfcompute.com/preview/v2/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://api.sfcompute.com/preview/v2/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([
    'pool' => '<string>',
    'image' => '<string>',
    'instance_sku' => 'isku_k3R-nX9vLm7Qp2Yw5Jd8F',
    'name' => 'my-resource-name',
    'cloud_init_user_data' => 'IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=',
    'enable_public_ipv4' => true,
    'firewall' => 'frwl_k3R-nX9vLm7Qp2Yw5Jd8F',
    'tags' => [
        'env' => 'prod',
        'team' => 'infra'
    ],
    '_preview_enable_infiniband' => false
  ]),
  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://api.sfcompute.com/preview/v2/instances"

	payload := strings.NewReader("{\n  \"pool\": \"<string>\",\n  \"image\": \"<string>\",\n  \"instance_sku\": \"isku_k3R-nX9vLm7Qp2Yw5Jd8F\",\n  \"name\": \"my-resource-name\",\n  \"cloud_init_user_data\": \"IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=\",\n  \"enable_public_ipv4\": true,\n  \"firewall\": \"frwl_k3R-nX9vLm7Qp2Yw5Jd8F\",\n  \"tags\": {\n    \"env\": \"prod\",\n    \"team\": \"infra\"\n  },\n  \"_preview_enable_infiniband\": false\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://api.sfcompute.com/preview/v2/instances")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"pool\": \"<string>\",\n  \"image\": \"<string>\",\n  \"instance_sku\": \"isku_k3R-nX9vLm7Qp2Yw5Jd8F\",\n  \"name\": \"my-resource-name\",\n  \"cloud_init_user_data\": \"IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=\",\n  \"enable_public_ipv4\": true,\n  \"firewall\": \"frwl_k3R-nX9vLm7Qp2Yw5Jd8F\",\n  \"tags\": {\n    \"env\": \"prod\",\n    \"team\": \"infra\"\n  },\n  \"_preview_enable_infiniband\": false\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.sfcompute.com/preview/v2/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  \"pool\": \"<string>\",\n  \"image\": \"<string>\",\n  \"instance_sku\": \"isku_k3R-nX9vLm7Qp2Yw5Jd8F\",\n  \"name\": \"my-resource-name\",\n  \"cloud_init_user_data\": \"IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=\",\n  \"enable_public_ipv4\": true,\n  \"firewall\": \"frwl_k3R-nX9vLm7Qp2Yw5Jd8F\",\n  \"tags\": {\n    \"env\": \"prod\",\n    \"team\": \"infra\"\n  },\n  \"_preview_enable_infiniband\": false\n}"

response = http.request(request)
puts response.read_body
{
  "id": "inst_k3R-nX9vLm7Qp2Yw5Jd8F",
  "resource_path": "<string>",
  "owner": "<string>",
  "workspace": "<string>",
  "workspace_id": "<string>",
  "name": "<string>",
  "object": "instance",
  "capacity": {
    "id": "cap_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "<string>"
  },
  "pool": {
    "id": "<string>",
    "name": "<string>"
  },
  "created_at": 1738972800,
  "updated_at": 1738972800,
  "image": {
    "id": "image_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "<string>"
  },
  "cloud_init_user_data_used": true,
  "instance_sku": {
    "object": "instance_sku",
    "id": "isku_k3R-nX9vLm7Qp2Yw5Jd8F",
    "alias": "<string>"
  },
  "managed_by": {
    "id": "<string>",
    "name": "<string>",
    "object": "deployment"
  },
  "cloud_init_user_data": "IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=",
  "enable_public_ipv4": true,
  "public_ip": "<string>",
  "firewall": "frwl_k3R-nX9vLm7Qp2Yw5Jd8F",
  "tags": {
    "env": "prod",
    "team": "infra"
  },
  "expected_shutdown_at": 1738972800
}
{
  "error": {
    "type": "authentication_error",
    "message": "<string>"
  }
}
{
  "error": {
    "type": "forbidden",
    "message": "<string>"
  }
}
{
  "error": {
    "type": "not_found",
    "message": "<string>"
  }
}
{
  "error": {
    "type": "unprocessable_entity",
    "message": "<string>",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>"
      }
    ]
  }
}
{
  "error": {
    "type": "api_error",
    "message": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

Create an API token using sf tokens create or at https://sfcompute.com/account/api-keys.

Body

application/json
​
pool
string
required

A resource path like 'sfc:pool:acme:prod:my-pool' or an ID. Resource paths are human-readable but not stable - they change when resources are renamed or moved. IDs are stable and permanent.

Pattern: (pool_[0-9a-zA-Z_-]{1,21})|(sfc:pool:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){2,2})
Example:

"pool_k3R-nX9vLm7Qp2Yw5Jd8F"

​
image
string
required

A resource path like 'sfc:image:acme:prod:my-image' or an ID. Resource paths are human-readable but not stable - they change when resources are renamed or moved. IDs are stable and permanent.

Pattern: (image_[0-9a-zA-Z_-]{1,21}|vmi_[0-9a-zA-Z_-]{1,21})|(sfc:image:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){2,2})
Example:

"image_k3R-nX9vLm7Qp2Yw5Jd8F"

​
instance_sku
required

Instance SKU this instance will run on. The instance is pinned to the SKU's underlying hardware pool at create time — it will not land on any other SKU. See GET /preview/v2/instance_skus to enumerate the SKUs visible to your account.

Pattern: isku_[0-9a-zA-Z_-]{1,21}
Example:

"isku_k3R-nX9vLm7Qp2Yw5Jd8F"

​
name
null | string
Required string length: 1 - 255
Pattern: [a-zA-Z0-9][a-zA-Z0-9._-]{0,254}
Example:

"my-resource-name"

​
cloud_init_user_data
string<byte>

Base64-encoded cloud-init user data. Maximum 64KB.

Example:

"IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo="

​
enable_public_ipv4
boolean

Whether to assign a public IPv4 address to this instance. When false (the default), only SSH (TCP port 22) is open on the instance and no other ports accept inbound traffic. When true, the chosen instance_sku must advertise the SKU property public_ipv4 with value "yes".

​
firewall
null | string

Firewall to attach to this instance's public IP, e.g. sfc:firewall:acme:prod:default to use the workspace's auto-managed default firewall.

Required when enable_public_ipv4 = true; forbidden otherwise.

Pattern: (frwl_[0-9a-zA-Z_-]{1,21})|(sfc:firewall:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){2,2})
Example:

"frwl_k3R-nX9vLm7Qp2Yw5Jd8F"

​
tags
null | object

Optional metadata tags for this instance.

Example:
{ "env": "prod", "team": "infra" }
​
priority_level
null | enum<string>

Instance priority. Omit to default to normal.

Available options:
yield,
normal,
preferred,
critical
​
_preview_enable_infiniband
boolean
default:false

Experimental — subject to change or removal without notice. Enables InfiniBand. The chosen instance_sku must support InfiniBand.

Example:

false

Response

Instance created.

​
id
required

Accepts the canonical prefix below; additional legacy prefixes are aliased for read compatibility. Writes always emit the canonical form.

Pattern: inst_[0-9a-zA-Z_-]{1,21}
Example:

"inst_k3R-nX9vLm7Qp2Yw5Jd8F"

​
resource_path
string
required

A resource path for a instance resource. Format: sfc:instance:::.

Pattern: sfc:instance:([a-zA-Z0-9._-]+:){2}[a-zA-Z0-9._-]+
Example:

"sfc:instance:<account_id>:<workspace>:<name>"

​
owner
string
required
Required string length: 1 - 255
Pattern: [a-zA-Z0-9][a-zA-Z0-9._-]{0,254}
Example:

"my-resource-name"

​
workspace
string
required
Required string length: 1 - 255
Pattern: [a-zA-Z0-9][a-zA-Z0-9._-]{0,254}
Example:

"my-resource-name"

​
workspace_id
string
required
Pattern: wksp_[0-9a-zA-Z_-]{1,21}
Example:

"wksp_k3R-nX9vLm7Qp2Yw5Jd8F"

​
name
string
required
Required string length: 1 - 255
Pattern: [a-zA-Z0-9][a-zA-Z0-9._-]{0,254}
Example:

"my-resource-name"

​
object
string
default:instance
required
read-only
Allowed value: "instance"
​
status
enum<string>
required

awaiting_allocation when waiting for compute allocation on its capacity, running once assigned and the physical machine is running (still takes time for the image to be downloaded and booted), terminated when stopped by the user or after running out of allocation, failed on hardware fault.

Available options:
awaiting_allocation,
running,
terminated,
failed
​
capacity
object
required

Deprecated — use pool. The pool this instance is utilizing.

​
pool
object
required

A pool referenced by id and name.

​
created_at
integer<int64>
required

Unix timestamp.

Example:

1738972800

​
updated_at
integer<int64>
required

Unix timestamp (seconds) when the instance was last updated.

Example:

1738972800

​
image
object
required

Image this instance was launched from.

​
cloud_init_user_data_used
boolean
required

Whether cloud-init user data is configured for this instance.

​
instance_sku
null | object

Instance SKU this instance is running on. Only present when assigned to a physical machine. Carries the SKU's human-readable name when one is registered.

​
managed_by
object

Deployment or spot deployment managing this instance, if any.

​
cloud_init_user_data
string<byte>

Base64-encoded cloud-init user data.

Example:

"IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo="

​
enable_public_ipv4
boolean

Whether this instance requires a public IPv4 address. When false, only SSH (TCP port 22) is open on the instance and no other ports accept inbound traffic.

​
public_ip
string

Public IPv4 address assigned to this instance. Present only when enable_public_ipv4 = true; omitted otherwise.

​
firewall
null | string

Firewall attached to this instance's public IP. Omitted when the instance has enable_public_ipv4 = false.

Pattern: frwl_[0-9a-zA-Z_-]{1,21}
Example:

"frwl_k3R-nX9vLm7Qp2Yw5Jd8F"

​
tags
null | object

Metadata tags attached to this instance.

Example:
{ "env": "prod", "team": "infra" }
​
expected_shutdown_at
null | integer<int64>

Predicted Unix timestamp at which this node will be terminated because its capacity drops below the count of running nodes. null if no shutdown is scheduled in the predictable horizon — either the capacity covers this node indefinitely, or a future capacity increase blocks the prediction. Recomputed on every read.

Example:

1738972800

​
priority_level
null | enum<string>

Instance priority. Lower-priority instances are terminated first when the capacity's quota drops below the running-instance count.

Available options:
yield,
normal,
preferred,
critical