openapi: 3.1.0
info:
title: sfc-api Account Instances API
description: Public preview API - subject to change. See https://docs.sfcompute.com/preview/roadmap for details.
version: 0.1.0
x-apievangelist:
method: searched
generated: '2026-07-21'
source: Reconstructed from per-operation OpenAPI blocks published on https://docs.sfcompute.com/preview/api-reference/* (Mintlify). 65 pages merged; paths + components unioned verbatim.
note: Public preview API (subject to change). Base path /preview/v2 under server https://api.sfcompute.com.
servers:
- url: https://api.sfcompute.com
security:
- bearer_auth: []
tags:
- name: Instances
description: Spin up instances in a capacity to use your available compute.
paths:
/preview/v2/instances:
post:
tags:
- Instances
summary: Create instance
description: '> ⚠️ This endpoint is in [public preview](/preview/roadmap).
Create an instance.'
operationId: create_instance
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateInstanceRequest'
required: true
responses:
'201':
description: Instance created.
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Capacity not found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'422':
description: Validation error (e.g. capacity limit reached).
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
get:
tags:
- Instances
summary: List instances
description: '> ⚠️ This endpoint is in [public preview](/preview/roadmap).
List all instances.'
operationId: list_instances
parameters:
- name: workspace
in: query
description: Scope the returned list to a single workspace (ID, resource path, or name). Without it, the returned list spans every workspace the caller has requisite permissions on.
required: false
schema:
$ref: '#/components/schemas/ResourcePathOrId_WorkspaceId'
- name: id
in: query
description: Filter by instance ID (repeatable).
required: false
schema:
type: array
items:
$ref: '#/components/schemas/InstanceId'
style: form
explode: true
example: inst_k3R-nX9vLm7Qp2Yw5Jd8F
- name: pool
in: query
description: Filter by pool (repeatable). Instances on any of the given pools match.
required: false
schema:
type: array
items:
$ref: '#/components/schemas/ResourcePathOrId_PoolId'
style: form
explode: true
- name: status
in: query
description: Filter by instance status (repeatable).
required: false
schema:
type: array
items:
$ref: '#/components/schemas/InstanceStatus'
style: form
explode: true
- name: created_after
in: query
description: Filter to instances created at or after this Unix timestamp (seconds).
required: false
schema:
type: integer
format: int64
- name: created_before
in: query
description: Filter to instances created at or before this Unix timestamp (seconds).
required: false
schema:
type: integer
format: int64
- name: instance_sku
in: query
description: Filter by instance SKU (repeatable). Instances on any of the given SKUs match.
required: false
schema:
type: array
items:
$ref: '#/components/schemas/InstanceSkuId'
style: form
explode: true
- name: limit
in: query
required: false
schema:
type: integer
format: u-int32
default: 50
maximum: 200
minimum: 1
- name: starting_after
in: query
description: Cursor for forward pagination (from a previous response's `cursor` field).
required: false
schema:
$ref: '#/components/schemas/InstancesCursor'
- name: ending_before
in: query
description: Cursor for backward pagination.
required: false
schema:
$ref: '#/components/schemas/InstancesCursor'
- name: include
in: query
description: Additional fields to include in the response.
required: false
schema:
type: array
items:
$ref: '#/components/schemas/InstanceInclude'
- name: tag
in: query
description: 'Filter by tag key-value pair (repeatable). Format: `key=value` (the `=` between key and value must be percent-encoded in the URL).'
required: false
schema:
type: array
items:
type: string
style: form
explode: true
- name: tag_key
in: query
description: Filter by tag key existence (repeatable). Returns resources that have a tag with this key, regardless of the value.
required: false
schema:
type: array
items:
type: string
style: form
explode: true
responses:
'200':
description: Paginated list of instances.
content:
application/json:
schema:
$ref: '#/components/schemas/ListInstancesResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Capacity not found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'422':
description: Validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
patch:
tags:
- Instances
summary: Update multiple instances
description: '> ⚠️ This endpoint is in [public preview](/preview/roadmap).
Update one or more instances atomically. All listed instances must be in the same workspace; mixed-workspace batches are rejected with 422.'
operationId: batch_patch_instances
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BatchPatchInstancesRequest'
required: true
responses:
'200':
description: Instances updated.
content:
application/json:
schema:
$ref: '#/components/schemas/BatchPatchInstancesResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'422':
description: Unknown instance, cross-workspace batch, or batch over the entry cap.
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
/preview/v2/instances/{id}:
delete:
tags:
- Instances
summary: Delete instance
description: '> ⚠️ This endpoint is in [public preview](/preview/roadmap).
Delete an instance.'
operationId: delete_instance
parameters:
- name: id
in: path
required: true
schema:
type: string
description: 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.
examples:
- inst_k3R-nX9vLm7Qp2Yw5Jd8F
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})
responses:
'204':
description: Instance deleted.
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Instance not found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: Instance must be terminated before deletion.
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
get:
tags:
- Instances
summary: Get instance
description: '> ⚠️ This endpoint is in [public preview](/preview/roadmap).
Retrieve an instance by ID or name.'
operationId: fetch_instance
parameters:
- name: id
in: path
required: true
schema:
type: string
description: 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.
examples:
- inst_k3R-nX9vLm7Qp2Yw5Jd8F
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})
responses:
'200':
description: Instance details.
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Instance not found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
patch:
tags:
- Instances
summary: Update instance
description: '> ⚠️ This endpoint is in [public preview](/preview/roadmap).
Update an instance. Omitted fields are left unchanged.'
operationId: update_instance
parameters:
- name: id
in: path
required: true
schema:
type: string
description: 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.
examples:
- inst_k3R-nX9vLm7Qp2Yw5Jd8F
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})
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchInstanceRequest'
required: true
responses:
'200':
description: Instance updated.
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceResponse'
'400':
description: Validation error (e.g. duplicate name).
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Instance not found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'422':
description: Validation error (e.g. field not applicable to this instance).
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
/preview/v2/instances/{id}/logs:
get:
tags:
- Instances
summary: Get instance logs
description: '> ⚠️ This endpoint is in [public preview](/preview/roadmap).
Retrieve logs for an instance.'
operationId: get_instance_logs
parameters:
- name: id
in: path
required: true
schema:
type: string
description: 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.
examples:
- inst_k3R-nX9vLm7Qp2Yw5Jd8F
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})
- name: seqnum_before
in: query
description: Return logs with `seqnum` less than or equal to this value.
required: false
schema:
type: integer
format: u-int64
minimum: 0
- name: seqnum_after
in: query
description: Return logs with `seqnum` greater than or equal to this value.
required: false
schema:
type: integer
format: u-int64
minimum: 0
- name: realtime_timestamp_before
in: query
description: Due to clock synchronization, some earlier log messages may have a realtime timestamp after this value.
required: false
schema:
$ref: '#/components/schemas/UnixEpoch'
- name: realtime_timestamp_after
in: query
description: Due to clock synchronization, some later log messages may have a realtime timestamp before this value.
required: false
schema:
$ref: '#/components/schemas/UnixEpoch'
- name: sort_by
in: query
required: false
schema:
type: string
enum:
- seqnum
- -seqnum
- name: limit
in: query
required: false
schema:
type: integer
format: u-int64
default: 100
maximum: 2500
minimum: 1
responses:
'200':
description: Log chunks.
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceLogsResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Instance not found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'422':
description: Validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
/preview/v2/instances/{id}/replace:
post:
tags:
- Instances
summary: Replace instance
description: '> ⚠️ This endpoint is in [public preview](/preview/roadmap).
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.'
operationId: replace_instance
parameters:
- name: id
in: path
required: true
schema:
type: string
description: 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.
examples:
- inst_k3R-nX9vLm7Qp2Yw5Jd8F
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})
- name: Idempotency-Key
in: header
description: Optional key that makes the request idempotent. Retries with the same key return the original replacement.
required: false
schema:
type:
- string
- 'null'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReplaceInstanceRequest'
required: true
responses:
'201':
description: Replacement instance created.
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceResponse'
'400':
description: Invalid request (e.g. requested name already in use).
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Instance not found or already terminated.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'422':
description: Validation error (e.g. image not available).
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
/preview/v2/instances/{id}/ssh:
get:
tags:
- Instances
summary: Get instance SSH info
description: '> ⚠️ This endpoint is in [public preview](/preview/roadmap).
Retrieve SSH connection details for an instance.'
operationId: get_instance_ssh
parameters:
- name: id
in: path
required: true
schema:
type: string
description: 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.
examples:
- inst_k3R-nX9vLm7Qp2Yw5Jd8F
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})
responses:
'200':
description: SSH connection details.
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceSshInfo'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: SSH details not available.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
/preview/v2/instances/{id}/terminate:
post:
tags:
- Instances
summary: Terminate instance
description: '> ⚠️ This endpoint is in [public preview](/preview/roadmap).
Terminates a running instance. Terminated instances can not be restarted.'
operationId: terminate_instance
parameters:
- name: id
in: path
required: true
schema:
type: string
description: 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.
examples:
- inst_k3R-nX9vLm7Qp2Yw5Jd8F
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})
responses:
'200':
description: Instance terminated.
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Instance not found or already terminated.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
components:
schemas:
InstanceSkuId:
oneOf:
- type: string
examples:
- isku_k3R-nX9vLm7Qp2Yw5Jd8F
pattern: isku_[0-9a-zA-Z_-]{1,21}
- type: string
description: Legacy alias prefix; accepted on read, never emitted on write.
pattern: clus_[0-9a-zA-Z_-]{1,21}
description: Accepts the canonical prefix below; additional legacy prefixes are aliased for read compatibility. Writes always emit the canonical form.
InternalServerError:
type: object
required:
- error
properties:
error:
type: object
required:
- type
- message
properties:
type:
type: string
const: api_error
default: api_error
readOnly: true
message:
type: string
x-speakeasy-error-message: true
DeploymentId:
type: string
examples:
- depl_k3R-nX9vLm7Qp2Yw5Jd8F
pattern: depl_[0-9a-zA-Z_-]{1,21}
InstancePriority:
type: string
description: '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`.'
enum:
- yield
- normal
- preferred
- critical
SpotDeploymentId:
type: string
examples:
- spot_k3R-nX9vLm7Qp2Yw5Jd8F
pattern: spot_[0-9a-zA-Z_-]{1,21}
UnprocessableEntityError:
type: object
required:
- error
properties:
error:
type: object
required:
- type
- message
properties:
type:
type: string
const: unprocessable_entity
default: unprocessable_entity
readOnly: true
message:
type: string
x-speakeasy-error-message: true
details:
type: array
items:
$ref: '#/components/schemas/ErrorDetail'
ErrorDetail:
type: object
required:
- code
- message
properties:
field:
type:
- string
- 'null'
description: The field that caused the error (for validation errors)
code:
type: string
description: Specific error code for this detail
message:
type: string
description: Human-readable error message
FirewallId:
type: string
examples:
- frwl_k3R-nX9vLm7Qp2Yw5Jd8F
pattern: frwl_[0-9a-zA-Z_-]{1,21}
WorkspaceId:
type: string
examples:
- wksp_k3R-nX9vLm7Qp2Yw5Jd8F
pattern: wksp_[0-9a-zA-Z_-]{1,21}
InstanceLogChunk:
type: object
required:
- timestamp_realtime
- timestamp_monotonic_secs
- timestamp_monotonic_nanos
- seqnum
- data
properties:
timestamp_realtime:
$ref: '#/components/schemas/UnixEpoch'
description: Wall-clock time. Unix timestamp.
timestamp_monotonic_secs:
type: integer
format: int64
description: Monotonic clock seconds.
timestamp_monotonic_nanos:
type: integer
format: u-int32
description: Nanosecond component of the monotonic clock.
minimum: 0
seqnum:
type: integer
format: u-int64
minimum: 0
data:
type: string
format: byte
description: Base-64 encoded raw console output.
example: SGVsbG8gV29ybGQK
contentEncoding: base64
ConflictError:
type: object
required:
- error
properties:
error:
type: object
required:
- type
- message
properties:
type:
type: string
const: conflict
default: conflict
readOnly: true
message:
type: string
x-speakeasy-error-message: true
details:
type: array
items:
$ref: '#/components/schemas/ErrorDetail'
ResourcePathOrId_PoolId:
type: string
description: A resource path like 'sfc:pool:acme:prod:my-pool' _or_ an ID. Resource paths are human-readable but not stable - they change when resources are renamed or moved. IDs are stable and permanent.
examples:
- pool_k3R-nX9vLm7Qp2Yw5Jd8F
pattern: (pool_[0-9a-zA-Z_-]{1,21})|(sfc:pool:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){2,2})
BadRequestError:
type: object
required:
- error
properties:
error:
type: object
required:
- type
- message
properties:
type:
type: string
const: invalid_request_error
default: invalid_request_error
readOnly: true
message:
type: string
x-speakeasy-error-message: true
details:
type: array
items:
$ref: '#/components/schemas/ErrorDetail'
PatchInstanceRequest:
type: object
properties:
name:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/Name'
tags:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/Tags'
description: 'Metadata tags. Full replacement semantics: replaces all existing tags. Omit to leave tags unchanged. Set to `null` to clear all tags.'
priority_level:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/InstancePriority'
description: Instance priority. Omit to leave unchanged.
InstancesCursor:
type: string
examples:
- nodec_gqXR7s0Kj5mHvE2wNpLc4Q
pattern: ^nodec_[A-Za-z0-9_-]+$
ImageId:
oneOf:
- type: string
examples:
- image_k3R-nX9vLm7Qp2Yw5Jd8F
pattern: image_[0-9a-zA-Z_-]{1,21}
- type: string
description: Legacy alias prefix; accepted on read, never emitted on write.
pattern: vmi_[0-9a-zA-Z_-]{1,21}
description: Accepts the canonical prefix below; additional legacy prefixes are aliased for read compatibility. Writes always emit the canonical form.
UnauthorizedError:
type: object
required:
- error
properties:
error:
type: object
required:
- type
- message
properties:
type:
type: string
const: authentication_error
default: authentication_error
readOnly: true
message:
type: string
x-speakeasy-error-message: true
ResourcePathOrId_FirewallId:
type: string
description: A resource path like 'sfc:firewall:acme:prod:my-firewall' _or_ an ID. Resource paths are human-readable but not stable - they change when resources are renamed or moved. IDs are stable and permanent.
examples:
- frwl_k3R-nX9vLm7Qp2Yw5Jd8F
pattern: (frwl_[0-9a-zA-Z_-]{1,21})|(sfc:firewall:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){2,2})
InstanceId:
oneOf:
- type: string
examples:
- inst_k3R-nX9vLm7Qp2Yw5Jd8F
pattern: inst_[0-9a-zA-Z_-]{1,21}
- type: string
description: Legacy alias prefix; accepted on read, never emitted on write.
pattern: vm_[0-9a-zA-Z_-]{1,21}
description: Accepts the canonical prefix below; additional legacy prefixes are aliased for read compatibility. Writes always emit the canonical form.
InstanceScope:
type: object
required:
- id
- resource_path
-
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/the-san-francisco-compute-company/refs/heads/main/openapi/the-san-francisco-compute-company-instances-api-openapi.yml