> ## 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 deployment > > ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states). Create a generic deployment that uses capacity already owned in a pool, or a spot deployment that buys capacity for a specific instance SKU at or below a maximum rate. ## OpenAPI ````yaml /openapi.json post /preview/v2/deployments openapi: 3.1.0 info: title: sfc-api description: >- SF Compute API. Routes under /v2 are stable; routes under /preview/v2 are public preview - subject to change. 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: Subnets description: Private networks for instance-to-instance communication within a zone. - 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/deployments: post: tags: - Deployments summary: Create deployment description: >- > ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states). Create a generic deployment that uses capacity already owned in a pool, or a spot deployment that buys capacity for a specific instance SKU at or below a maximum rate. operationId: create_deployment requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateDeploymentResourceRequest' required: true responses: '201': description: Deployment created. content: application/json: schema: $ref: '#/components/schemas/DeploymentResource' '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: Not found. content: application/json: schema: $ref: '#/components/schemas/NotFoundError' '409': description: Pool and instance SKU already have an incompatible automation. content: application/json: schema: $ref: '#/components/schemas/ConflictError' '422': description: Validation failed. 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: CreateDeploymentResourceRequest: oneOf: - allOf: - $ref: '#/components/schemas/CreateDeploymentRequest' - type: object description: >- Maintain the target number of instances using capacity already owned in the selected pool. required: - kind properties: kind: type: string const: generic default: generic readOnly: true description: >- Maintain the target number of instances using capacity already owned in the selected pool. - allOf: - $ref: '#/components/schemas/CreateSpotDeploymentRequest' - type: object description: >- Buy capacity for a specific instance SKU at or below the maximum rate, then maintain the target number of instances on that capacity. required: - kind properties: kind: type: string const: spot default: spot readOnly: true description: >- Buy capacity for a specific instance SKU at or below the maximum rate, then maintain the target number of instances on that capacity. description: >- Instance-lifecycle automation. A generic deployment uses capacity already owned in a pool. A spot deployment also buys the capacity it needs. Deployments do not supersede procurements. Use a procurement when capacity should be bought or sold independently of creating instances. DeploymentResource: oneOf: - $ref: '#/components/schemas/DeploymentResponse' - $ref: '#/components/schemas/SpotDeploymentResponse' discriminator: propertyName: object mapping: deployment: '#/components/schemas/sfc-api_DeploymentResponse' spot_deployment: '#/components/schemas/sfc-api_SpotDeploymentResponse' 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 CreateDeploymentRequest: type: object description: >- A generic deployment maintains a target number of instances using capacity already owned in a pool. It does not buy additional capacity. required: - pool - instance_sku - instance_template - target_instance_count properties: name: oneOf: - type: 'null' - $ref: '#/components/schemas/Name' pool: $ref: '#/components/schemas/ResourcePathOrId_PoolId' instance_sku: $ref: '#/components/schemas/InstanceSkuId' instance_template: $ref: '#/components/schemas/ResourcePathOrId_InstanceTemplateId' description: >- Template whose image and cloud-init user data are used for every instance created by this deployment. target_instance_count: type: integer format: int32 instance_name_template: $ref: '#/components/schemas/NameTemplate' CreateSpotDeploymentRequest: type: object description: >- A spot deployment buys capacity for a specific instance SKU at or below a maximum rate, then maintains a target number of instances on that capacity. required: - pool - instance_sku - instance_template - target_instance_count - max_buy_price_dollars_per_node_hour properties: name: oneOf: - type: 'null' - $ref: '#/components/schemas/Name' pool: $ref: '#/components/schemas/ResourcePathOrId_PoolId' instance_sku: $ref: '#/components/schemas/InstanceSkuId' description: Instance SKU this spot deployment's orders will run on. instance_template: $ref: '#/components/schemas/ResourcePathOrId_InstanceTemplateId' description: >- Template whose image and cloud-init user data are used for every instance created by this deployment. target_instance_count: type: integer format: int32 max_buy_price_dollars_per_node_hour: $ref: '#/components/schemas/DollarsPerNodeHour' min_runtime_minutes: type: - integer - 'null' format: int32 description: >- Minimum continuous capacity window, in minutes, the spot deployment tries to purchase before launching each target instance. Boot time counts toward this window. Below 10 minutes, an instance may have very little or no usable runtime after boot; use shorter windows only for fast-starting, interruption-tolerant workloads. Minimum runtimes of 2 minutes or lower do not include a preemption notice. Defaults to 10 minutes. maximum: 1440 minimum: 1 instance_name_template: $ref: '#/components/schemas/NameTemplate' DeploymentResponse: allOf: - $ref: '#/components/schemas/DeploymentScope' - type: object required: - object - capacity - pool - instance_sku - instance_template - enabled - target_instance_count - instance_name_template - status - created_at - updated_at properties: object: type: string const: deployment default: deployment readOnly: true capacity: $ref: '#/components/schemas/CapacitySummary' description: Deprecated — use `pool`. pool: $ref: '#/components/schemas/PoolSummaryPreview' instance_sku: $ref: '#/components/schemas/InstanceSkuSummary' instance_template: $ref: '#/components/schemas/InstanceTemplateSummary' enabled: type: boolean target_instance_count: type: integer format: int32 instance_name_template: $ref: '#/components/schemas/NameTemplate' status: $ref: '#/components/schemas/ReconciliationStatus' description: Result of reconciling this deployment's target instance count. created_at: $ref: '#/components/schemas/UnixEpoch' updated_at: $ref: '#/components/schemas/UnixEpoch' SpotDeploymentResponse: allOf: - $ref: '#/components/schemas/SpotDeploymentScope' - type: object required: - object - pool - instance_template - instance_sku - enabled - target_instance_count - max_buy_price_dollars_per_node_hour - min_runtime_minutes - instance_name_template - status - created_at - updated_at properties: object: type: string const: spot_deployment default: spot_deployment readOnly: true pool: $ref: '#/components/schemas/PoolSummaryPreview' instance_template: $ref: '#/components/schemas/InstanceTemplateSummary' instance_sku: $ref: '#/components/schemas/InstanceSkuSummary' description: Instance SKU this spot deployment's orders are pinned to. enabled: type: boolean target_instance_count: type: integer format: int32 max_buy_price_dollars_per_node_hour: $ref: '#/components/schemas/DollarsPerNodeHour' min_runtime_minutes: type: integer format: int32 description: >- Minimum continuous capacity window, in minutes, the spot deployment tries to purchase before launching each target instance. Boot time counts toward this window. Below 10 minutes, an instance may have very little or no usable runtime after boot; use shorter windows only for fast-starting, interruption-tolerant workloads. Minimum runtimes of 2 minutes or lower do not include a preemption notice. maximum: 1440 minimum: 1 instance_name_template: $ref: '#/components/schemas/NameTemplate' status: $ref: '#/components/schemas/ReconciliationStatus' description: >- Result of reconciling both capacity acquisition and target instances. created_at: $ref: '#/components/schemas/UnixEpoch' updated_at: $ref: '#/components/schemas/UnixEpoch' description: >- A spot deployment combines capacity procurement and instance lifecycle: it buys compute up to a maximum price and runs instances on the secured pool. The standalone procurements API remains available for managing capacity without creating instances. 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 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}) 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_InstanceTemplateId: type: string description: >- A resource path like 'sfc:instance_template:acme:prod:my-instance_template' _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: - itmpl_k3R-nX9vLm7Qp2Yw5Jd8F pattern: >- (itmpl_[0-9a-zA-Z_-]{1,21}|ntmpl_[0-9a-zA-Z_-]{1,21})|(sfc:instance_template:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){2,2}) NameTemplate: type: string description: >- A name template using {{variable}} syntax. Available variables: {{adjective}} (~128 random adjectives), {{noun}} (~128 random nouns), {{nanoid(N)}} (N-character alphanumeric identifier, 1 ≤ N ≤ 21). The template must produce enough unique combinations to avoid collisions — equivalent to at least the default template {{adjective}}-{{noun}}-{{nanoid(6)}} (~1 quadrillion possibilities). Must start with an alphanumeric character. Resolved names are limited to 255 characters. examples: - my-fleet-{{nanoid(9)}} maxLength: 512 DollarsPerNodeHour: type: string description: >- Price in dollars per node-hour, encoded as a decimal string. Prices are rounded to the nearest $0.000060/node-hour market tick. This is one microdollar per node-minute. Responses contain the rounded value with six decimal places. Inputs must contain a decimal point, be non-negative, and not exceed $500/node-hour. examples: - '18.000000' pattern: ^\d+\.\d+$ DeploymentScope: type: object required: - id - resource_path - owner - workspace - workspace_id - name properties: id: $ref: '#/components/schemas/DeploymentId' resource_path: $ref: '#/components/schemas/deploymentResourcePath_DeploymentId' owner: $ref: '#/components/schemas/Name' workspace: $ref: '#/components/schemas/Name' workspace_id: $ref: '#/components/schemas/WorkspaceId' name: $ref: '#/components/schemas/Name' CapacitySummary: type: object required: - id - name properties: id: $ref: '#/components/schemas/CapacityId' name: $ref: '#/components/schemas/Name' PoolSummaryPreview: type: object description: A pool referenced by id and name. required: - id - name properties: id: $ref: '#/components/schemas/PoolId' name: $ref: '#/components/schemas/Name' 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' InstanceTemplateSummary: type: object required: - id - name properties: id: $ref: '#/components/schemas/InstanceTemplateId' name: $ref: '#/components/schemas/Name' ReconciliationStatus: type: object required: - state - message properties: state: $ref: '#/components/schemas/AutomationStatus' message: type: string UnixEpoch: type: integer format: int64 description: Unix timestamp. example: 1738972800 SpotDeploymentScope: type: object required: - id - resource_path - owner - workspace - workspace_id - name properties: id: $ref: '#/components/schemas/SpotDeploymentId' resource_path: $ref: '#/components/schemas/spot_deploymentResourcePath_SpotDeploymentId' owner: $ref: '#/components/schemas/Name' workspace: $ref: '#/components/schemas/Name' workspace_id: $ref: '#/components/schemas/WorkspaceId' name: $ref: '#/components/schemas/Name' DeploymentId: type: string examples: - depl_k3R-nX9vLm7Qp2Yw5Jd8F pattern: depl_[0-9a-zA-Z_-]{1,21} deploymentResourcePath_DeploymentId: type: string description: >- A resource path for a deployment resource. Format: sfc:deployment:::. examples: - sfc:deployment::: pattern: sfc:deployment:([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} InstanceTemplateId: oneOf: - type: string examples: - itmpl_k3R-nX9vLm7Qp2Yw5Jd8F pattern: itmpl_[0-9a-zA-Z_-]{1,21} - type: string description: Legacy alias prefix; accepted on read, never emitted on write. pattern: ntmpl_[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. AutomationStatus: type: string enum: - info - warning - error SpotDeploymentId: type: string examples: - spot_k3R-nX9vLm7Qp2Yw5Jd8F pattern: spot_[0-9a-zA-Z_-]{1,21} spot_deploymentResourcePath_SpotDeploymentId: type: string description: >- A resource path for a spot_deployment resource. Format: sfc:spot_deployment:::. examples: - sfc:spot_deployment::: pattern: sfc:spot_deployment:([a-zA-Z0-9._-]+:){2}[a-zA-Z0-9._-]+ 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. ````