Sign in

v1

latestOpenAPI 3.1.02026-07-2665179189.7 KB
Instances

Update instance

⚠️ This endpoint is in public preview.

Update an instance. Omitted fields are left unchanged.

patch/preview/v2/instances/{id}

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

Request body

namestring
tagsTags
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 request

{
  "name": "my-resource-name",
  "tags": {
    "env": "prod",
    "team": "infra"
  }
}

Response

Instance updated.

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
}