openapi: 3.0.1
info:
  title: SF Compute Account Orders API
  description: REST API for the SF Compute (San Francisco Compute Company) GPU compute marketplace. Place buy/sell market orders for blocks of H100 GPU-hours, list and retrieve tradable cluster contracts, request live market quotes, read account balance, and provision managed-Kubernetes clusters, nodes, and VM instances. All endpoints require a Bearer API token generated with `sf tokens create`.
  termsOfService: https://sfcompute.com/terms
  contact:
    name: SF Compute Support
    email: hello@sfcompute.com
  version: v0
servers:
- url: https://api.sfcompute.com/v0
security:
- bearerAuth: []
tags:
- name: Orders
paths:
  /orders:
    get:
      operationId: listOrders
      tags:
      - Orders
      summary: List orders
      description: List market orders for the authenticated account with filtering, sorting, and pagination.
      parameters:
      - name: side
        in: query
        schema:
          type: string
          enum:
          - buy
          - sell
      - name: instance_type
        in: query
        schema:
          type: string
          example: h100i
      - name: min_price
        in: query
        schema:
          type: integer
          description: Minimum price in cents.
      - name: max_price
        in: query
        schema:
          type: integer
      - name: only_open
        in: query
        schema:
          type: boolean
      - name: only_filled
        in: query
        schema:
          type: boolean
      - name: only_cancelled
        in: query
        schema:
          type: boolean
      - name: sort_by
        in: query
        schema:
          type: string
          enum:
          - created_at
          - start_time
      - name: sort_direction
        in: query
        schema:
          type: string
          enum:
          - ASC
          - DESC
      - name: limit
        in: query
        schema:
          type: integer
      - name: offset
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: A list of orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'
    post:
      operationId: placeOrder
      tags:
      - Orders
      summary: Place an order
      description: Place a buy or sell market order. Buy orders specify an instance type, quantity, price, duration, and start time. Sell orders list time from an existing contract back to the market.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/PlaceBuyOrder'
              - $ref: '#/components/schemas/PlaceSellOrder'
      responses:
        '200':
          description: The placed order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    delete:
      operationId: cancelAllOrders
      tags:
      - Orders
      summary: Cancel all open orders
      responses:
        '200':
          description: Orders cancelled.
  /orders/{id}:
    get:
      operationId: getOrder
      tags:
      - Orders
      summary: Get an order
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    delete:
      operationId: cancelOrder
      tags:
      - Orders
      summary: Cancel an order
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Order cancelled.
  /orders/{id}/clusters:
    get:
      operationId: getOrderClusters
      tags:
      - Orders
      summary: Get clusters for an order
      description: Returns the clusters provisioned from a filled order.
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Clusters associated with the order.
components:
  parameters:
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: string
  schemas:
    OrderFlags:
      type: object
      properties:
        market:
          type: boolean
        post_only:
          type: boolean
        ioc:
          type: boolean
        prorate:
          type: boolean
    OrderList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Order'
    PlaceBuyOrder:
      type: object
      required:
      - side
      - quantity
      - price
      - instance_type
      - duration
      - start_at
      properties:
        side:
          type: string
          enum:
          - buy
        quantity:
          type: integer
          description: Number of nodes.
        price:
          type: integer
          description: Total price in cents.
        instance_type:
          type: string
          example: h100i
        duration:
          type: integer
          description: Duration in seconds.
        start_at:
          type: string
          description: ISO 8601 timestamp or "NOW".
    Order:
      type: object
      properties:
        object:
          type: string
          enum:
          - order
        id:
          type: string
        side:
          type: string
          enum:
          - buy
          - sell
        instance_type:
          type: string
          example: h100i
        price:
          type: integer
          description: Price in cents.
        quantity:
          type: integer
        start_at:
          type: string
          format: date-time
        end_at:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - pending
          - rejected
          - open
          - cancelled
          - filled
          - expired
        executed:
          type: boolean
        execution_price:
          type: integer
        cancelled:
          type: boolean
        cluster:
          type: string
        created_at:
          type: string
          format: date-time
        flags:
          $ref: '#/components/schemas/OrderFlags'
    PlaceSellOrder:
      type: object
      required:
      - side
      - quantity
      - price
      - start_at
      - end_at
      - contract_id
      properties:
        side:
          type: string
          enum:
          - sell
        quantity:
          type: integer
        price:
          type: integer
          description: Total price in cents.
        start_at:
          type: string
          format: date-time
        end_at:
          type: string
          format: date-time
        contract_id:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API token created with `sf tokens create`, sent as `Authorization: Bearer <token>`.'