Skip to main content
PATCH
Update instance

Authorizations

Authorization
string
header
required

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

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
name
null | string
Required string length: 1 - 255
Pattern: [a-zA-Z0-9][a-zA-Z0-9._-]{0,254}
Example:

"my-resource-name"

tags
null | object

Metadata tags. Full replacement semantics: replaces all existing tags. Omit to leave tags unchanged. Set to null to clear all tags.

Example:
priority_level
null | enum<string>

Instance priority. Omit to leave unchanged.

Available options:
yield,
normal,
preferred,
critical

Response

Instance updated.

Identity block flattened into [InstanceResponse]. Response-only: handlers build it from the resolver's [crate::types::resource_path::InstanceScope] at the response boundary.

id
string
required
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>"

workspace
object
required

Workspace this instance belongs to.

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

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

Available options:
awaiting_allocation,
running,
terminated,
failed
sku
object
required

SKU this instance is pinned to.

created_at
integer<int64>
required

Unix timestamp.

Example:

1738972800

_preview_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. Fetch the data itself from GET /instances/{id}/cloud_init_user_data.

pool
null | object

Pool this instance is utilizing.

managed_by
object

Deployment or spot deployment managing this instance, if any.

_preview_enable_public_ipv4
boolean

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

_preview_public_ip
string

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

_preview_firewall
null | string

Preview. Firewall attached to this instance's public IP. Omitted when the instance has _preview_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:
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