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

> > ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Place a buy or sell order.



## OpenAPI

````yaml /preview/openapi.json post /preview/v2/orders
openapi: 3.1.0
info:
  title: sfc-api
  description: >-
    SF Compute API public-preview routes — subject to change. Prefer the stable
    /v2 routes where a resource has graduated.
  version: 0.1.0
servers:
  - url: https://api.sfcompute.com
security:
  - bearer_auth: []
tags:
  - name: Limits
    description: Account limits and current usage.
  - 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: VPCs
    description: Isolated networks with routed subnets within one availability zone.
  - 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: 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: Faults
    description: Report problems with your resources.
  - name: InfiniBand Partitions
    description: Isolated InfiniBand networks for groups of instances.
  - 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/orders:
    post:
      tags:
        - Orders
      summary: Create order
      description: >-
        > ⚠️ This endpoint is in [public
        preview](/preview/roadmap#feature-states).


        Place a buy or sell order.
      operationId: create_order
      parameters:
        - name: Idempotency-Key
          in: header
          description: >-
            Unique key to ensure idempotent order creation. If provided,
            duplicate requests with the same key will not place a new order and
            return the original order.
          required: false
          schema:
            type:
              - string
              - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v2.CreateOrderRequestPreview'
        required: true
      responses:
        '201':
          description: Order created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v2.OrderResponsePreview'
        '400':
          description: Malformed request parameters or body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '402':
          description: Insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequiredError'
        '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: The Idempotency-Key was already used for a different order.
          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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '503':
          description: Service temporarily unavailable. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableError'
components:
  schemas:
    v2.CreateOrderRequestPreview:
      type: object
      required:
        - pool
        - side
        - instance_sku
        - allocation_schedule_delta
        - limit_price_dollars_per_node_hour
      properties:
        pool:
          $ref: '#/components/schemas/ResourcePathOrId_PoolId'
          description: Target pool that receives compute when filled.
        side:
          $ref: '#/components/schemas/Side'
        allow_standing:
          type: boolean
          description: >-
            If true, the order rests on the order book until it fills, is
            cancelled, or its end time passes. If false, the order is cancelled
            immediately if it does not fill.
        allow_partial:
          type: boolean
          description: >-
            If true, the order may fill partially — fewer nodes and/or a subset
            of the requested time window. The filled time may be disjoint.
        instance_sku:
          $ref: '#/components/schemas/InstanceSkuId'
          description: >-
            Instance SKU this order will fill on. Rejected at submission if the
            SKU id is not registered.
        allocation_schedule_delta:
          $ref: '#/components/schemas/Schedule'
          description: >-
            Change in capacity if the order fills (added on `buy`, subtracted on
            `sell`). Must be a single time range: one `node_count` held constant
            from `start_at` to `end_at`, with both set. `start_at` and `end_at`
            are Unix timestamps in seconds on the [allocation schedule
            grid](https://docs.sfcompute.com/api-reference/platform/get-platform-constants#response-allocation-schedule-grid);
            `start_at` can also be the current time. `node_count` must be
            between 1 and 10000.
        limit_price_dollars_per_node_hour:
          $ref: '#/components/schemas/DollarsPerNodeHour'
    v2.OrderResponsePreview:
      type: object
      required:
        - object
        - id
        - capacity
        - pool
        - side
        - allow_standing
        - instance_sku
        - allocation_schedule_delta
        - filled_allocation_schedule_delta
        - limit_price_dollars_per_node_hour
        - status
        - created_at
      properties:
        object:
          type: string
          const: order
          default: order
          readOnly: true
        id:
          $ref: '#/components/schemas/OrderId'
        capacity:
          $ref: '#/components/schemas/CapacitySummary'
          description: >-
            Deprecated — use `pool`. Target pool that receives or loses compute
            if this order fills (depending on order type).
        pool:
          $ref: '#/components/schemas/PoolSummaryPreview'
        side:
          $ref: '#/components/schemas/Side'
        allow_standing:
          type: boolean
          description: >-
            If true, the order stays in the order book until either fills, is
            explicitly cancelled, or the order end time is reached resulting in
            automatic cancellation. If false, the order is cancelled immediately
            if it doesn't fill.
        allow_partial:
          type: boolean
          description: >-
            If true, the order may fill partially — fewer nodes and/or a subset
            of the requested time window.
        instance_sku:
          $ref: '#/components/schemas/InstanceSkuSummary'
          description: >-
            Instance SKU this order is pinned to. Carries the SKU's
            human-readable name when one is registered.
        allocation_schedule_delta:
          $ref: '#/components/schemas/Schedule'
          description: >-
            Change in capacity if the order fills. Must be a single time range
            with both `start_at` and `end_at`.
        filled_allocation_schedule_delta:
          $ref: '#/components/schemas/Schedule'
          description: >-
            The total portion of the requested schedule that has filled. Once
            `status` is `cancelled`, this is final and remains available on
            later get and list responses. Empty for orders with no fills; the
            unfilled remainder is `allocation_schedule_delta` minus this.
        limit_price_dollars_per_node_hour:
          $ref: '#/components/schemas/DollarsPerNodeHour'
        status:
          $ref: '#/components/schemas/OrderStatus'
        created_at:
          $ref: '#/components/schemas/UnixEpoch'
        created_by:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/v2.OrderPrincipal'
              description: >-
                Principal that placed the order — the human user when known,
                otherwise the API token that placed it. `null` for orders that
                predate attribution. Always present (value-or-null) like other
                order attributes, since every order conceptually has a creator.
        filled_at:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UnixEpoch'
        filled_average_price_dollars_per_node_hour:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/DollarsPerNodeHour'
        fills:
          type: array
          items:
            $ref: '#/components/schemas/v2.OrderFill'
          description: >-
            Complete list of fills produced by this order. Once `status` is
            `cancelled`, this list is final and remains available on later get
            and list responses. Omitted for orders with no fills.
        cancelled_at:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UnixEpoch'
    BadRequestError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - message
          properties:
            type:
              type: string
              const: invalid_request_error
              default: invalid_request_error
            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
            message:
              type: string
              x-speakeasy-error-message: true
    PaymentRequiredError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - message
          properties:
            type:
              type: string
              const: payment_required
              default: payment_required
            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
            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
            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
            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
            message:
              type: string
              x-speakeasy-error-message: true
            details:
              type: array
              items:
                $ref: '#/components/schemas/ErrorDetail'
    RateLimitedError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - message
          properties:
            type:
              type: string
              const: rate_limited
              default: rate_limited
            message:
              type: string
              x-speakeasy-error-message: true
    InternalServerError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - message
          properties:
            type:
              type: string
              const: api_error
              default: api_error
            message:
              type: string
              x-speakeasy-error-message: true
    ServiceUnavailableError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - message
          properties:
            type:
              type: string
              const: service_unavailable
              default: service_unavailable
            message:
              type: string
              x-speakeasy-error-message: true
    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})
    Side:
      type: string
      enum:
        - sell
        - buy
    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.
    Schedule:
      type: array
      items:
        $ref: '#/components/schemas/ScheduleEntry'
      description: >-
        Node count over time, as a list of `[start_at, end_at)` time ranges.


        Example: 5 nodes from t=0 to t=3600 is `[{"start_at": 0, "end_at": 3600,
        "node_count": 5}]`.


        `start_at` and `end_at` must be 60-second aligned, `node_count` must be
        non-negative. On non-final entries, `end_at` may be omitted (inferred
        from the next entry's `start_at`); gaps fill with `node_count: 0`. Order
        and transfer times must also be on the [allocation schedule
        grid](https://docs.sfcompute.com/api-reference/platform/get-platform-constants#response-allocation-schedule-grid),
        except a start at the current time.


        In responses, a non-empty array always closes with a terminator entry
        whose `end_at` is `null` (the unbounded tail) and, for a bounded
        schedule, `node_count: 0`; an empty schedule is returned as `[]`.
    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+$
    OrderId:
      type: string
      examples:
        - ordr_k3R-nX9vLm7Qp2Yw5Jd8F
      pattern: ordr_[0-9a-zA-Z_-]{1,21}
    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'
    OrderStatus:
      type: string
      description: >-
        The status of an order in the system.


        `pending` = received and waiting to be matched.


        `filled` = order executed.


        `partially_filled` = the order matched part of its requested capacity
        and remains active for the remainder.


        `standing` = the order is waiting for a match.


        `cancelled` = the order was cancelled either automatically (not a
        standing order and didn't immediately fill, current time past `end_at`,
        the account can no longer cover it, or the account can no longer trade)
        or by explicit cancellation.


        `rejected` = the account couldn't cover the order when it came to match,
        or a system error occurred.
      enum:
        - pending
        - filled
        - partially_filled
        - rejected
        - cancelled
        - standing
    UnixEpoch:
      type: integer
      format: int64
      description: Unix timestamp.
      example: 1738972800
    v2.OrderPrincipal:
      type: object
      description: >-
        The principal that placed an order. `type` distinguishes the two cases:
        a user carries `email` (when an email identity exists); a token carries
        `name`. The inapplicable field is omitted.
      required:
        - id
        - type
      properties:
        id:
          type: string
          description: >-
            `users.id` for a user principal, `api_tokens.id` for a token
            principal.
        type:
          $ref: '#/components/schemas/v2.OrderPrincipalKind'
        email:
          type:
            - string
            - 'null'
          description: >-
            Email of the user, when the principal is a user with a recorded
            email.
        name:
          type:
            - string
            - 'null'
          description: Name of the API token, when the principal is a token.
    v2.OrderFill:
      type: object
      description: >-
        A single fill event: the capacity and price this order executed at in
        one matching event.
      required:
        - filled_at
        - allocation_schedule_delta
        - price_dollars_per_node_hour
      properties:
        filled_at:
          $ref: '#/components/schemas/UnixEpoch'
        allocation_schedule_delta:
          $ref: '#/components/schemas/Schedule'
          description: >-
            Capacity change this fill delivered. Quantities are always positive;
            `side` on the parent order determines whether this added or removed
            capacity.
        price_dollars_per_node_hour:
          $ref: '#/components/schemas/DollarsPerNodeHour'
    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
    ScheduleEntry:
      type: object
      description: >-
        A `[start_at, end_at)` time range with a fixed `node_count`. `end_at` is
        `null` only on the final entry, marking an unbounded tail.
      required:
        - start_at
        - node_count
      properties:
        start_at:
          $ref: '#/components/schemas/UnixEpoch'
        end_at:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UnixEpoch'
        node_count:
          type: integer
          format: int32
    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.
    Name:
      type: string
      examples:
        - my-resource-name
      maxLength: 255
      minLength: 1
      pattern: '[a-zA-Z0-9][a-zA-Z0-9._-]{0,254}'
    PoolId:
      type: string
      examples:
        - pool_k3R-nX9vLm7Qp2Yw5Jd8F
      pattern: pool_[0-9a-zA-Z_-]{1,21}
    v2.OrderPrincipalKind:
      type: string
      description: >-
        Whether an order's `created_by` principal is a human user or an API
        token.
      enum:
        - user
        - token
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Create an API token using `sf tokens create` or at
        https://sfcompute.com/dashboard/tokens.

````