Sign in

v1

latestOpenAPI 3.1.02026-07-2665179189.7 KB
Instances

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.

post/preview/v2/instances/{id}/replace

Path parameters

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

Example:inst_k3R-nX9vLm7Qp2Yw5Jd8F

Headers

Idempotency-Keystring nullable

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

Request body

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

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

namestring

Example request

{
  "image": "image_k3R-nX9vLm7Qp2Yw5Jd8F",
  "cloud_init_user_data": "IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=",
  "name": "my-resource-name"
}

Response

Replacement instance created.

resource_pathstring required

A resource path for a instance resource. Format: sfc:instance:<account>:<workspace>:<name>.

ownerstring required
workspacestring required
workspace_idstring required
namestring required
object'instance' required
status'awaiting_allocation' | 'running' | 'terminated' | 'failed' 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.

Values are not exhaustive across API versions. Clients should tolerate new statuses.

created_atinteger required

Unix timestamp.

updated_atinteger required

Unix timestamp.

cloud_init_user_data_usedboolean required

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

cloud_init_user_datastring byte

Base64-encoded cloud-init user data.

enable_public_ipv4boolean

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_ipstring

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

firewallstring
tagsTags
expected_shutdown_atinteger

Unix timestamp.

priority_level'yield' | 'normal' | 'preferred' | 'critical'

Instance priority — a relative ranking that determines which instances the system prefers to keep running when capacity is constrained. When a capacity's quota drops below its running-instance count, instances are terminated in priority order (lower first).

Ordering: yield < normal < preferred < critical.

Example response

{
  "id": "inst_k3R-nX9vLm7Qp2Yw5Jd8F",
  "resource_path": "sfc:instance:<account_id>:<workspace>:<name>",
  "owner": "my-resource-name",
  "workspace": "my-resource-name",
  "workspace_id": "wksp_k3R-nX9vLm7Qp2Yw5Jd8F",
  "name": "my-resource-name",
  "instance_sku": {
    "id": "isku_k3R-nX9vLm7Qp2Yw5Jd8F",
    "alias": "my-resource-name"
  },
  "capacity": {
    "id": "cap_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "my-resource-name"
  },
  "pool": {
    "id": "pool_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "my-resource-name"
  },
  "created_at": 1738972800,
  "updated_at": 1738972800,
  "image": {
    "id": "image_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "my-resource-name"
  },
  "managed_by": {
    "id": "depl_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "my-resource-name"
  },
  "cloud_init_user_data": "IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=",
  "firewall": "frwl_k3R-nX9vLm7Qp2Yw5Jd8F",
  "tags": {
    "env": "prod",
    "team": "infra"
  },
  "expected_shutdown_at": 1738972800
}