> ## 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 > Place a buy or sell order. Orders fill on a single instance SKU matching the order's `requirements`. By default orders fill completely or not at all; set `allow_partial` to permit a partial fill. Order filling is asynchronous; poll `GET /v2/orders/{id}` to check the order's state. ## OpenAPI ````yaml /preview/openapi.json post /v2/orders 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/orders: post: tags: - Orders summary: Create order description: >- Place a buy or sell order. Orders fill on a single instance SKU matching the order's `requirements`. By default orders fill completely or not at all; set `allow_partial` to permit a partial fill. Order filling is asynchronous; poll `GET /v2/orders/{id}` to check the order's state. 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.CreateOrderRequest' required: true responses: '201': description: Order created. content: application/json: schema: $ref: '#/components/schemas/v2.OrderResponse' '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' '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' '503': description: Service temporarily unavailable. Try again later. content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailableError' components: schemas: v2.CreateOrderRequest: type: object required: - pool - side - allow_standing - allow_partial - 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. sku: type: string description: >- SKU this order will fill on. Rejected at submission if the SKU id is not registered. Any id spelling is accepted. example: sku_k3R-nX9vLm7Qp2Yw5Jd8F pattern: sku_[0-9a-zA-Z_-]{1,21} 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. Each must be hour-aligned (a multiple of 3600), or any minute (a multiple of 60) up to the end of the next hour. `start_at` may be at most 5 minutes in the past. `end_at` must be after `start_at` (so the window is at least 1 minute), must be in the future, and may be at most 10 years ahead of now. `node_count` must be between 1 and 10000. limit_price_dollars_per_node_hour: $ref: '#/components/schemas/DollarsPerNodeHour' v2.OrderResponse: type: object required: - object - id - pool - workspace - side - allow_standing - sku - allocation_schedule_delta - filled_allocation_schedule_delta - limit_price_dollars_per_node_hour - state - created_at properties: object: type: string const: order default: order readOnly: true id: $ref: '#/components/schemas/OrderId' pool: $ref: '#/components/schemas/PoolSummary' description: >- Target pool that receives or loses compute if this order fills (depending on order type). workspace: $ref: '#/components/schemas/WorkspaceSummary' description: Workspace that owns the order's pool. 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. sku: $ref: '#/components/schemas/SkuSummary' description: >- 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 `state` 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' state: $ref: '#/components/schemas/OrderStatus' description: Current state of the order. created_at: $ref: '#/components/schemas/UnixEpoch' filled_at: oneOf: - type: 'null' - $ref: '#/components/schemas/UnixEpoch' fills: type: array items: $ref: '#/components/schemas/v2.OrderFill' description: >- Complete list of contracts produced by this order. Once `state` 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 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 PaymentRequiredError: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string const: payment_required default: payment_required 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 ServiceUnavailableError: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string const: service_unavailable default: service_unavailable readOnly: true 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 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`. 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} 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' 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' 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`. OrderStatus: type: string description: >- The status of an order in the system. `pending` = not resolved/processed yet. `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, or current time past `end_at`) or by explicit cancellation. `rejected` = validation/system error occurred. enum: - pending - filled - partially_filled - rejected - cancelled - standing UnixEpoch: type: integer format: int64 description: Unix timestamp. example: 1738972800 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 PoolId: type: string examples: - pool_k3R-nX9vLm7Qp2Yw5Jd8F pattern: pool_[0-9a-zA-Z_-]{1,21} Name: type: string examples: - my-resource-name maxLength: 255 minLength: 1 pattern: '[a-zA-Z0-9][a-zA-Z0-9._-]{0,254}' WorkspaceId: type: string examples: - wksp_k3R-nX9vLm7Qp2Yw5Jd8F pattern: wksp_[0-9a-zA-Z_-]{1,21} SkuId: type: string examples: - sku_k3R-nX9vLm7Qp2Yw5Jd8F pattern: sku_[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. ````