> ## 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

> Create an instance.



## OpenAPI

````yaml /preview/openapi.json post /v2/instances
openapi: 3.1.0
info:
  title: sfc-api
  description: >-
    SF Compute API. Routes under /preview/v2 are preview - subject to change;
    prefer the /v2 routes.
  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:
  /v2/instances:
    post:
      tags:
        - Instances
      summary: Create instance
      description: 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'
        '400':
          description: Invalid request.
          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: SKU not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '409':
          description: An instance with this name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictError'
        '422':
          description: Validation error (e.g. capacity limit reached).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityError'
        '429':
          description: >-
            Rate limit exceeded. Retry after the interval indicated by the
            rate-limit response headers.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
components:
  schemas:
    CreateInstanceRequest:
      type: object
      required:
        - pool
        - image
        - sku
      properties:
        name:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Name'
        pool:
          $ref: '#/components/schemas/ResourcePathOrId_PoolId'
        image:
          $ref: '#/components/schemas/ResourcePathOrId_ImageId'
        sku:
          type: string
          description: >-
            SKU this instance will run on, as a `sku_`-prefixed id. The instance
            is pinned to the SKU's underlying hardware pool at create time — it
            will not land on any other SKU. See `GET /v2/skus` to enumerate the
            SKUs visible to your account.
          example: sku_k3R-nX9vLm7Qp2Yw5Jd8F
          pattern: sku_[0-9a-zA-Z_-]{1,21}
        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
        _preview_enable_public_ipv4:
          type: boolean
          description: >-
            **Preview.** 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 `sku` must advertise the SKU property
            `public_ipv4` with value `"yes"`.
        _preview_firewall:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ResourcePathOrId_FirewallId'
              description: >-
                **Preview.** 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 `_preview_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: Enables InfiniBand. The chosen `sku` must support InfiniBand.
          default: false
          example: false
    InstanceResponse:
      allOf:
        - $ref: '#/components/schemas/InstanceScope'
        - type: object
          required:
            - object
            - state
            - sku
            - created_at
            - _preview_updated_at
            - image
            - cloud_init_user_data_used
          properties:
            object:
              type: string
              const: instance
              default: instance
              readOnly: true
            state:
              $ref: '#/components/schemas/InstanceStatus'
            sku:
              $ref: '#/components/schemas/SkuSummary'
              description: SKU this instance is pinned to.
            pool:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/PoolSummary'
                  description: Pool this instance is utilizing.
            created_at:
              $ref: '#/components/schemas/UnixEpoch'
            _preview_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.
                Fetch the data itself from `GET
                /instances/{id}/cloud_init_user_data`.
            _preview_enable_public_ipv4:
              type: boolean
              description: >-
                **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:
              type: string
              description: >-
                **Preview.** Public IPv4 address assigned to this instance.
                Present only when `_preview_enable_public_ipv4 = true`; omitted
                otherwise.
            _preview_firewall:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/FirewallId'
                  description: >-
                    **Preview.** Firewall attached to this instance's public IP.
                    Omitted when the instance has `_preview_enable_public_ipv4 =
                    false`.
            tags:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/Tags'
                  description: Metadata tags attached to this instance.
            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.
    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'
    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
    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'
    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})
    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
      description: >-
        Identity block flattened into [`InstanceResponse`]. Response-only:
        handlers build it from the resolver's
        [`crate::types::resource_path::InstanceScope`] at the response boundary.
      required:
        - id
        - resource_path
        - workspace
        - name
      properties:
        id:
          type: string
          example: inst_k3R-nX9vLm7Qp2Yw5Jd8F
          pattern: inst_[0-9a-zA-Z_-]{1,21}
        resource_path:
          $ref: '#/components/schemas/instanceResourcePath_InstanceId'
        workspace:
          $ref: '#/components/schemas/WorkspaceSummary'
          description: Workspace this instance belongs to.
        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
    SkuSummary:
      type: object
      description: A SKU referenced by id and alias.
      required:
        - object
        - id
        - alias
      properties:
        object:
          type: string
          const: sku
          default: sku
          readOnly: true
        id:
          $ref: '#/components/schemas/SkuId'
        alias:
          $ref: '#/components/schemas/Name'
          description: >-
            A short, unique among live, human-recognizable name for this SKU.
            For display only - reference the SKU by `id`.
    PoolSummary:
      type: object
      description: A pool referenced by id and name.
      required:
        - object
        - id
        - name
      properties:
        object:
          type: string
          const: pool_summary
          default: pool_summary
          readOnly: true
        id:
          $ref: '#/components/schemas/PoolId'
        name:
          $ref: '#/components/schemas/Name'
    UnixEpoch:
      type: integer
      format: int64
      description: Unix timestamp.
      example: 1738972800
    ImageSummary:
      type: object
      description: An image referenced by id and name.
      required:
        - object
        - id
        - name
      properties:
        object:
          type: string
          const: image_summary
          default: image_summary
          readOnly: true
        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
    instanceResourcePath_InstanceId:
      type: string
      description: >-
        A resource path for a instance resource. Format:
        sfc:instance:<account>:<workspace>:<name>.
      examples:
        - sfc:instance:<account_id>:<workspace>:<name>
      pattern: sfc:instance:([a-zA-Z0-9._-]+:){2}[a-zA-Z0-9._-]+
    WorkspaceSummary:
      type: object
      description: A workspace referenced by id and name.
      required:
        - object
        - id
        - name
      properties:
        object:
          type: string
          const: workspace_summary
          default: workspace_summary
          readOnly: true
        id:
          $ref: '#/components/schemas/WorkspaceId'
        name:
          $ref: '#/components/schemas/Name'
    SkuId:
      type: string
      examples:
        - sku_k3R-nX9vLm7Qp2Yw5Jd8F
      pattern: sku_[0-9a-zA-Z_-]{1,21}
    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'
    WorkspaceId:
      type: string
      examples:
        - wksp_k3R-nX9vLm7Qp2Yw5Jd8F
      pattern: wksp_[0-9a-zA-Z_-]{1,21}
    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.

````