Skip to main content
POST
/
preview
/
v2
/
instances
/
{id}
/
replace
Replace instance
curl --request POST \
  --url https://api.sfcompute.com/preview/v2/instances/{id}/replace \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "image": "<string>",
  "cloud_init_user_data": "IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=",
  "name": "my-resource-name"
}
'
{
  "id": "inst_k3R-nX9vLm7Qp2Yw5Jd8F",
  "resource_path": "<string>",
  "owner": "<string>",
  "workspace": "<string>",
  "workspace_id": "<string>",
  "name": "<string>",
  "object": "instance",
  "capacity": {
    "id": "<string>",
    "name": "<string>"
  },
  "created_at": 1738972800,
  "image": {
    "id": "image_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "<string>"
  },
  "cloud_init_user_data_used": true,
  "instance_sku": {
    "id": "isku_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "<string>"
  },
  "deployment": {
    "id": "<string>",
    "name": "<string>"
  },
  "cloud_init_user_data": "IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=",
  "tags": {
    "env": "prod",
    "team": "infra"
  },
  "expected_shutdown_at": 1738972800
}

Authorizations

​
Authorization
string
header
required

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

Headers

​
Idempotency-Key
string | null

Optional key that makes the request idempotent. Retries with the same key return the original replacement.

Path Parameters

​
id
string
required

A resource path like 'sfc:instance:acme:prod:my-instance' 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: (inst_[0-9a-zA-Z_-]{1,21}|vm_[0-9a-zA-Z_-]{1,21})|(sfc:instance:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){2,2})
Example:

"inst_k3R-nX9vLm7Qp2Yw5Jd8F"

Body

application/json

Request body for POST /v2/instances/{id}/replace. Terminates the target instance and creates a fresh one on the same capacity and SKU, with a new image (and optionally a new startup script / name). Capacity, SKU, subnet, public-IPv4, firewall, tags, and priority are inherited from the terminated instance.

​
image
string
required

Image to launch the replacement instance from.

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"

​
cloud_init_user_data
string<byte>

Base64-encoded cloud-init user data. Maximum 64KB. If omitted, the replacement starts with no startup script — you will not be able to SSH into it.

Example:

"IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo="

​
name
null | string

Optional name for the replacement. A name is generated if omitted. Must differ from the replaced instance's name, which stays reserved while that instance lingers in the terminated state.

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

"my-resource-name"

Response

Replacement 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

Capacity this instance is utilizing.

​
created_at
integer<int64>
required

Unix timestamp.

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
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.

​
deployment
object

Deployment managing this instance, if any.

​
cloud_init_user_data
string<byte>

Base64-encoded cloud-init user data.

Example:

"IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo="

​
tags
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