openapi: 3.0.1
info:
  title: SF Compute 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
  - name: Contracts
  - name: Prices
  - name: Clusters
  - name: Nodes
  - name: Balance
  - name: Account
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
        - Clusters
      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.
  /quote:
    get:
      operationId: getQuote
      tags:
        - Prices
      summary: Get a market quote
      description: >-
        Request an indicative market price for a desired instance type,
        quantity, start window, and duration. Returns a quote with the price
        in cents from which a per-GPU-hour rate can be derived. There is no
        single fixed price per GPU-hour; each block is priced by the market.
      parameters:
        - name: side
          in: query
          schema:
            type: string
            enum: [buy, sell]
        - name: instance_type
          in: query
          schema:
            type: string
            example: h100i
        - name: quantity
          in: query
          schema:
            type: integer
        - name: min_start_date
          in: query
          schema:
            type: string
            description: ISO 8601 timestamp or the literal "NOW".
        - name: max_start_date
          in: query
          schema:
            type: string
        - name: min_duration
          in: query
          schema:
            type: integer
            description: Minimum duration in seconds.
        - name: max_duration
          in: query
          schema:
            type: integer
        - name: cluster
          in: query
          schema:
            type: string
        - name: colocate_with
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A market quote, or null when no block is available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
  /contracts:
    get:
      operationId: listContracts
      tags:
        - Contracts
      summary: List contracts
      responses:
        '200':
          description: A list of contracts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractList'
  /contracts/{id}:
    get:
      operationId: getContract
      tags:
        - Contracts
      summary: Get a contract
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: The contract.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
  /procurements:
    get:
      operationId: listProcurements
      tags:
        - Clusters
      summary: List procurements
      description: List auto-scaling procurement fleets.
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of procurements.
    post:
      operationId: createProcurement
      tags:
        - Clusters
      summary: Create a procurement
      description: Create an auto-scaling procurement that maintains a target quantity of capacity.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created procurement.
  /procurements/{id}:
    get:
      operationId: getProcurement
      tags:
        - Clusters
      summary: Get a procurement
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: The procurement.
  /instances:
    get:
      operationId: listInstances
      tags:
        - Nodes
      summary: List instances
      responses:
        '200':
          description: A list of instances.
  /instances/{id}:
    get:
      operationId: getInstance
      tags:
        - Nodes
      summary: Get an instance
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: The instance.
  /zones:
    get:
      operationId: listZones
      tags:
        - Clusters
      summary: List zones
      responses:
        '200':
          description: A list of availability zones.
  /credentials:
    get:
      operationId: listCredentials
      tags:
        - Clusters
      summary: List credentials
      responses:
        '200':
          description: A list of cluster credentials (kubeconfig).
    post:
      operationId: createCredential
      tags:
        - Clusters
      summary: Create a credential
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created credential.
  /vms/instances:
    get:
      operationId: listVmInstances
      tags:
        - Nodes
      summary: List VM instances
      responses:
        '200':
          description: A list of VM instances.
  /balance:
    get:
      operationId: getBalance
      tags:
        - Balance
      summary: Get account balance
      description: Returns available and current account balance in cents.
      responses:
        '200':
          description: The account balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
  /transactions:
    get:
      operationId: listTransactions
      tags:
        - Balance
      summary: List transactions
      responses:
        '200':
          description: A list of account transactions.
  /tokens:
    get:
      operationId: listTokens
      tags:
        - Account
      summary: List API tokens
      responses:
        '200':
          description: A list of tokens.
    post:
      operationId: createToken
      tags:
        - Account
      summary: Create an API token
      responses:
        '200':
          description: The created token.
  /tokens/{id}:
    delete:
      operationId: deleteToken
      tags:
        - Account
      summary: Delete an API token
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Token deleted.
  /me:
    get:
      operationId: getMe
      tags:
        - Account
      summary: Get current account
      responses:
        '200':
          description: The authenticated account.
  /ping:
    get:
      operationId: ping
      tags:
        - Account
      summary: Health check
      security: []
      responses:
        '200':
          description: Service is reachable.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API token created with `sf tokens create`, sent as `Authorization: Bearer <token>`.'
  parameters:
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: string
  schemas:
    OrderList:
      type: object
      properties:
        object:
          type: string
          enum: [list]
        data:
          type: array
          items:
            $ref: '#/components/schemas/Order'
    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'
    OrderFlags:
      type: object
      properties:
        market:
          type: boolean
        post_only:
          type: boolean
        ioc:
          type: boolean
        prorate:
          type: boolean
    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".
    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
    QuoteResponse:
      type: object
      properties:
        object:
          type: string
          enum: [quote]
        quote:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Quote'
    Quote:
      type: object
      properties:
        price:
          type: integer
          description: Total price in cents for the quoted block.
        quantity:
          type: integer
        instance_type:
          type: string
        start_at:
          type: string
          format: date-time
        end_at:
          type: string
          format: date-time
    ContractList:
      type: object
      properties:
        object:
          type: string
          enum: [list]
        data:
          type: array
          items:
            $ref: '#/components/schemas/Contract'
    Contract:
      type: object
      properties:
        object:
          type: string
          enum: [contract]
        id:
          type: string
        status:
          type: string
          enum: [active, expired, upcoming, pending]
        instance_type:
          type: string
        created_at:
          type: string
          format: date-time
        cluster_id:
          type: string
        zone:
          type: string
        colocate_with:
          type: array
          items:
            type: string
        shape:
          type: object
          properties:
            intervals:
              type: array
              items:
                type: string
                format: date-time
            quantities:
              type: array
              items:
                type: integer
    Balance:
      type: object
      properties:
        available_balance_cents:
          type: integer
        current_balance_cents:
          type: integer