> ## Documentation Index > Fetch the complete documentation index at: https://docs.sfcompute.com/llms.txt > Use this file to discover all available pages before exploring further. # Create instance > > ⚠️ This endpoint is in [public preview](/preview/roadmap). Create an instance. ## OpenAPI ````yaml /preview/openapi.json post /preview/v2/instances openapi: 3.1.0 info: title: sfc-api description: >- Public preview API - subject to change. See https://docs.sfcompute.com/preview/roadmap for details. version: 0.1.0 servers: - url: https://api.sfcompute.com security: - bearer_auth: [] tags: - name: Account description: The authenticated account and logged-in user. - name: Pools description: A bucket of owned compute balance over time. - name: Orders description: >- Place orders targeting a capacity to increase your reserved compute balance during some time period. - name: Instance Templates description: Reusable instance configuration. - name: Images description: Custom machine images for instances. - name: Roles description: TOML-based permission role definitions. - name: Grants description: Bind principals (users or tokens) to roles on a workspace. - name: Tokens description: Workspace-scoped API tokens. - name: Instances description: Spin up instances in a capacity to use your available compute. - name: Instance SKU Catalog description: Browse available instance SKU property definitions. - name: Procurements description: Market automations that maintain capacity by placing buy/sell orders. - name: Deployments description: >- Deployment automations that maintain a fleet of instances, including spot deployments that buy capacity up to a maximum price. - name: Users description: Read-only access to users within the caller's organization. - name: Workspaces description: Resource containers scoped to an account. - name: Permissions description: Inspect what the caller is allowed to do. - name: Billing description: Billing profile, contacts, and auto top-up settings. - name: Orderbook description: >- Read-only orderbook visibility: bid/ask spread, depth, open and filled orders, and historical fills, keyed on hardware requirements + delivery window. - name: Orders description: >- Estimate an order before placing it: filled price, fee, and operational notices. 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' components: schemas: CreateInstanceRequest: type: object required: - pool - image - instance_sku properties: name: oneOf: - type: 'null' - $ref: '#/components/schemas/Name' pool: $ref: '#/components/schemas/ResourcePathOrId_PoolId' image: $ref: '#/components/schemas/ResourcePathOrId_ImageId' instance_sku: $ref: '#/components/schemas/InstanceSkuId' description: >- Instance SKU this instance will run on. The instance is pinned to the SKU's underlying hardware pool at create time — it will not land on any other SKU. See `GET /preview/v2/instance_skus` to enumerate the SKUs visible to your account. cloud_init_user_data: type: string format: byte description: >- Base64-encoded [cloud-init user data](https://cloudinit.readthedocs.io/en/latest/explanation/format/index.html). Maximum 64KB. example: IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo= contentEncoding: base64 enable_public_ipv4: type: boolean description: >- Whether to assign a public IPv4 address to this instance. When `false` (the default), only SSH (TCP port 22) is open on the instance and no other ports accept inbound traffic. When `true`, the chosen `instance_sku` must advertise the SKU property `public_ipv4` with value `"yes"`. firewall: oneOf: - type: 'null' - $ref: '#/components/schemas/ResourcePathOrId_FirewallId' description: >- Firewall to attach to this instance's public IP, e.g. `sfc:firewall:acme:prod:default` to use the workspace's auto-managed default firewall. Required when `enable_public_ipv4 = true`; forbidden otherwise. tags: oneOf: - type: 'null' - $ref: '#/components/schemas/Tags' description: Optional metadata tags for this instance. priority_level: oneOf: - type: 'null' - $ref: '#/components/schemas/InstancePriority' description: Instance priority. Omit to default to `normal`. _preview_enable_infiniband: type: boolean description: >- **Experimental — subject to change or removal without notice.** Enables InfiniBand. The chosen `instance_sku` must support InfiniBand. default: false example: false InstanceResponse: allOf: - $ref: '#/components/schemas/InstanceScope' - type: object required: - object - status - instance_sku - capacity - pool - created_at - updated_at - image - cloud_init_user_data_used properties: object: type: string const: instance default: instance readOnly: true status: $ref: '#/components/schemas/InstanceStatus' instance_sku: $ref: '#/components/schemas/InstanceSkuSummary' description: Instance SKU this instance is pinned to. capacity: $ref: '#/components/schemas/CapacitySummary' description: Deprecated — use `pool`. The pool this instance is utilizing. pool: $ref: '#/components/schemas/PoolSummary' created_at: $ref: '#/components/schemas/UnixEpoch' updated_at: $ref: '#/components/schemas/UnixEpoch' description: Unix timestamp (seconds) when the instance was last updated. image: $ref: '#/components/schemas/ImageSummary' description: Image this instance was launched from. managed_by: oneOf: - type: 'null' - $ref: '#/components/schemas/InstanceManagedBySummary' description: >- Deployment or spot deployment managing this instance, if any. cloud_init_user_data_used: type: boolean description: Whether cloud-init user data is configured for this instance. cloud_init_user_data: type: string format: byte description: >- Base64-encoded [cloud-init user data](https://cloudinit.readthedocs.io/en/latest/explanation/format/index.html). example: IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo= contentEncoding: base64 enable_public_ipv4: type: boolean description: >- 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_ip: type: string description: >- Public IPv4 address assigned to this instance. Present only when `enable_public_ipv4 = true`; omitted otherwise. firewall: oneOf: - type: 'null' - $ref: '#/components/schemas/FirewallId' description: >- Firewall attached to this instance's public IP. Omitted when the instance has `enable_public_ipv4 = false`. tags: oneOf: - type: 'null' - $ref: '#/components/schemas/Tags' description: Metadata tags attached to this instance. expected_shutdown_at: oneOf: - type: 'null' - $ref: '#/components/schemas/UnixEpoch' description: Deprecated. Always returned as `null`. priority_level: oneOf: - type: 'null' - $ref: '#/components/schemas/InstancePriority' description: >- Instance priority. Lower-priority instances are terminated first when the capacity's quota drops below the running-instance count. 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 ForbiddenError: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string const: forbidden default: forbidden readOnly: true message: type: string x-speakeasy-error-message: true NotFoundError: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string const: not_found default: not_found readOnly: true message: type: string x-speakeasy-error-message: true 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' 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 Name: type: string examples: - my-resource-name maxLength: 255 minLength: 1 pattern: '[a-zA-Z0-9][a-zA-Z0-9._-]{0,254}' 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}) ResourcePathOrId_ImageId: type: string description: >- 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. examples: - image_k3R-nX9vLm7Qp2Yw5Jd8F pattern: >- (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}) 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. 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}) Tags: type: object additionalProperties: type: string examples: - prod maxLength: 256 pattern: ^[^,=]{0,256}$ propertyNames: type: string examples: - env maxLength: 128 minLength: 1 pattern: ^[^_,= ][^,= ]{0,127}$ examples: - env: prod team: infra maxProperties: 50 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 InstanceScope: type: object required: - id - resource_path - owner - workspace - workspace_id - name properties: id: $ref: '#/components/schemas/InstanceId' resource_path: $ref: '#/components/schemas/instanceResourcePath_InstanceId' owner: $ref: '#/components/schemas/Name' workspace: $ref: '#/components/schemas/Name' workspace_id: $ref: '#/components/schemas/WorkspaceId' name: $ref: '#/components/schemas/Name' InstanceStatus: type: string description: >- `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. enum: - awaiting_allocation - running - terminated - failed x-speakeasy-unknown-values: true InstanceSkuSummary: type: object description: >- A summary of an instance SKU - its `id` and human-recognizable `alias` - embedded on resources that reference a SKU. required: - object - id - alias properties: object: type: string const: instance_sku default: instance_sku readOnly: true id: $ref: '#/components/schemas/InstanceSkuId' alias: $ref: '#/components/schemas/Name' CapacitySummary: type: object required: - id - name properties: id: $ref: '#/components/schemas/CapacityId' name: $ref: '#/components/schemas/Name' PoolSummary: type: object description: A pool referenced by id and name. required: - id - name properties: id: $ref: '#/components/schemas/PoolId' name: $ref: '#/components/schemas/Name' UnixEpoch: type: integer format: int64 description: Unix timestamp. example: 1738972800 ImageSummary: type: object required: - id - name properties: id: $ref: '#/components/schemas/ImageId' name: $ref: '#/components/schemas/Name' InstanceManagedBySummary: oneOf: - allOf: - $ref: '#/components/schemas/DeploymentSummary' - type: object required: - object properties: object: type: string const: deployment default: deployment readOnly: true - allOf: - $ref: '#/components/schemas/SpotDeploymentSummary' - type: object required: - object properties: object: type: string const: spot_deployment default: spot_deployment readOnly: true FirewallId: type: string examples: - frwl_k3R-nX9vLm7Qp2Yw5Jd8F pattern: frwl_[0-9a-zA-Z_-]{1,21} 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 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. instanceResourcePath_InstanceId: type: string description: >- A resource path for a instance resource. Format: sfc:instance:::. examples: - sfc:instance::: pattern: sfc:instance:([a-zA-Z0-9._-]+:){2}[a-zA-Z0-9._-]+ WorkspaceId: type: string examples: - wksp_k3R-nX9vLm7Qp2Yw5Jd8F pattern: wksp_[0-9a-zA-Z_-]{1,21} CapacityId: oneOf: - type: string examples: - cap_k3R-nX9vLm7Qp2Yw5Jd8F pattern: cap_[0-9a-zA-Z_-]{1,21} - type: string description: Legacy alias prefix; accepted on read, never emitted on write. pattern: pool_[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. PoolId: type: string examples: - pool_k3R-nX9vLm7Qp2Yw5Jd8F pattern: pool_[0-9a-zA-Z_-]{1,21} 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. DeploymentSummary: type: object required: - id - name properties: id: $ref: '#/components/schemas/DeploymentId' name: $ref: '#/components/schemas/Name' SpotDeploymentSummary: type: object required: - id - name properties: id: $ref: '#/components/schemas/SpotDeploymentId' name: $ref: '#/components/schemas/Name' DeploymentId: type: string examples: - depl_k3R-nX9vLm7Qp2Yw5Jd8F pattern: depl_[0-9a-zA-Z_-]{1,21} SpotDeploymentId: type: string examples: - spot_k3R-nX9vLm7Qp2Yw5Jd8F pattern: spot_[0-9a-zA-Z_-]{1,21} securitySchemes: bearer_auth: type: http scheme: bearer bearerFormat: JWT description: >- Create an API token using `sf tokens create` or at https://sfcompute.com/account/api-keys. ````