Replace instance
⚠️ This endpoint is in public preview.
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 and name). Capacity, SKU, subnet, public IPv4, firewall, tags, and priority are inherited from the replaced instance. The two operations happen in a single transaction. Pass an Idempotency-Key header to make retries safe: a repeated request returns the replacement created by the first attempt instead of creating another one.
Authorizations
Create an API token using sf tokens create or at https://sfcompute.com/account/api-keys.
Headers
Optional key that makes the request idempotent. Retries with the same key return the original replacement.
Path Parameters
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.
(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})"inst_k3R-nX9vLm7Qp2Yw5Jd8F"
Body
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 to launch the replacement instance from.
(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})"image_k3R-nX9vLm7Qp2Yw5Jd8F"
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.
"IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo="
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.
1 - 255[a-zA-Z0-9][a-zA-Z0-9._-]{0,254}"my-resource-name"
Response
Replacement instance created.
Accepts the canonical prefix below; additional legacy prefixes are aliased for read compatibility. Writes always emit the canonical form.
inst_[0-9a-zA-Z_-]{1,21}"inst_k3R-nX9vLm7Qp2Yw5Jd8F"
A resource path for a instance resource. Format: sfc:instance:::.
sfc:instance:([a-zA-Z0-9._-]+:){2}[a-zA-Z0-9._-]+"sfc:instance:<account_id>:<workspace>:<name>"
1 - 255[a-zA-Z0-9][a-zA-Z0-9._-]{0,254}"my-resource-name"
1 - 255[a-zA-Z0-9][a-zA-Z0-9._-]{0,254}"my-resource-name"
wksp_[0-9a-zA-Z_-]{1,21}"wksp_k3R-nX9vLm7Qp2Yw5Jd8F"
1 - 255[a-zA-Z0-9][a-zA-Z0-9._-]{0,254}"my-resource-name"
"instance"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.
Values are not exhaustive across API versions. Clients should tolerate new statuses.
awaiting_allocation, running, terminated, failed Instance SKU this instance is pinned to.
Deprecated — use pool. The pool this instance is utilizing.
A pool referenced by id and name.
Unix timestamp.
1738972800
Unix timestamp (seconds) when the instance was last updated.
1738972800
Image this instance was launched from.
Whether cloud-init user data is configured for this instance.
Deployment or spot deployment managing this instance, if any.
- Option 1
- Option 2
Base64-encoded cloud-init user data.
"IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo="
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 IPv4 address assigned to this instance. Present only when enable_public_ipv4 = true; omitted otherwise.
Firewall attached to this instance's public IP. Omitted when the instance has enable_public_ipv4 = false.
frwl_[0-9a-zA-Z_-]{1,21}"frwl_k3R-nX9vLm7Qp2Yw5Jd8F"
Metadata tags attached to this instance.
Deprecated. Always returned as null.
1738972800
Instance priority. Lower-priority instances are terminated first when the capacity's quota drops below the running-instance count.
yield, normal, preferred, critical