> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rook.pm/llms.txt
> Use this file to discover all available pages before exploring further.

# Save fair values

> Future extension. Save your own outcome probabilities or expected per-unit payouts in an authorized private scope_id. Each estimate pins a Rook outcome and market version and records your source, observation time and optional expiry.

The batch is atomic: validation or revision conflicts reject the entire batch. PROBABILITY requires a value in [0,1] and an explicit FULL_PAYOUT event; EXPECTED_PAYOUT requires its payout currency. Saved records return private IDs, server revisions and timestamps. These are customer estimates, not venue prices or Rook forecasts, and marginal values do not define joint scenario probabilities.

*Future extension.*

See the [integration guide](/guides/fair-values) for the workflow and interpretation of this response.


## OpenAPI

````yaml POST /fair-values:batchUpsert
openapi: 3.1.0
info:
  title: Rook API
  version: 0.1.0-design
  description: Markets, settlement relationships, scenarios, payouts and market data.
servers:
  - url: https://api.rook.pm/v1
    description: Proposed API origin; not an assertion these operations are callable.
security:
  - ApiKeyBearer: []
tags:
  - name: Reference data
    description: Events, unified markets and native-ID resolution.
  - name: Families and scenarios
    description: Family scope and versioned scenario columns.
  - name: Relationships and Combos
    description: Related-market discovery, selected-set inference and Combo interpretation.
  - name: Payouts and exposure
    description: Scoped per-unit payouts and stateless portfolio/candidate calculations.
  - name: Market data
    description: Current prices, history, L2 books, prints, statistics and published fees.
  - name: Fair values
    description: Future private customer estimates; not Rook forecasts.
  - name: Coverage and updates
    description: Supported capabilities and incremental semantic changes.
paths:
  /fair-values:batchUpsert:
    post:
      tags:
        - Fair values
      summary: Save fair values
      description: >-
        Future extension. Save your own outcome probabilities or expected
        per-unit payouts in an authorized private scope_id. Each estimate pins a
        Rook outcome and market version and records your source, observation
        time and optional expiry.


        The batch is atomic: validation or revision conflicts reject the entire
        batch. PROBABILITY requires a value in [0,1] and an explicit FULL_PAYOUT
        event; EXPECTED_PAYOUT requires its payout currency. Saved records
        return private IDs, server revisions and timestamps. These are customer
        estimates, not venue prices or Rook forecasts, and marginal values do
        not define joint scenario probabilities.
      operationId: batchUpsertFairValues
      parameters:
        - name: X-Client-Request-Id
          in: header
          required: false
          schema:
            type: string
          description: Caller correlation reference; not an idempotency guarantee.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpsertFairValuesRequest'
            example:
              scope_id: rates_desk
              fair_values:
                - outcome_id: out_fed_dec_2026_cut_yes
                  market_version: '1'
                  value_type: PROBABILITY
                  probability_event: FULL_PAYOUT
                  value: '0.46'
                  source: rates-desk-model-v3
                  observed_at: '2026-10-19T11:45:00Z'
                  valid_until: '2026-10-19T18:00:00Z'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUpsertFairValuesResponse'
              example:
                items:
                  - fair_value_id: fv_rates_cut_desk
                    scope_id: rates_desk
                    outcome_id: out_fed_dec_2026_cut_yes
                    market_version: '1'
                    value_type: PROBABILITY
                    probability_event: FULL_PAYOUT
                    value: '0.46'
                    source: rates-desk-model-v3
                    observed_at: '2026-10-19T11:45:00Z'
                    valid_until: '2026-10-19T18:00:00Z'
                    updated_at: '2026-10-19T12:00:00Z'
                    revision: '1'
                    status: CURRENT
                updated_at: '2026-10-19T12:00:00Z'
          headers:
            X-Request-Id:
              description: Server request trace ID.
              schema:
                type: string
                description: Opaque text identifier. Preserve its exact value.
                minLength: 1
components:
  schemas:
    BatchUpsertFairValuesRequest:
      type: object
      properties:
        scope_id:
          type: string
          description: Opaque text identifier. Preserve its exact value.
          minLength: 1
        fair_values:
          type: array
          items:
            $ref: '#/components/schemas/FairValueInput'
          minItems: 1
          description: >-
            Nonempty batch of explicit outcome estimates; all validations and
            revision preconditions pass before any write.
      required:
        - scope_id
        - fair_values
      additionalProperties: false
    BatchUpsertFairValuesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FairValue'
        updated_at:
          type: string
          format: date-time
      required:
        - items
        - updated_at
      additionalProperties: true
    FairValueInput:
      type: object
      properties:
        outcome_id:
          type: string
          minLength: 1
          description: Rook payout-side ID. YES and NO have separate IDs.
        market_version:
          type: string
          description: Opaque text identifier. Preserve its exact value.
          minLength: 1
        value_type:
          type: string
          enum:
            - PROBABILITY
            - EXPECTED_PAYOUT
        probability_event:
          type: string
          enum:
            - FULL_PAYOUT
        value:
          $ref: '#/components/schemas/Decimal'
        currency:
          type: string
        source:
          type: string
        observed_at:
          type: string
          format: date-time
        valid_until:
          type: string
          format: date-time
        if_revision:
          type: string
          description: Opaque text identifier. Preserve its exact value.
          minLength: 1
      required:
        - outcome_id
        - market_version
        - value_type
        - value
        - source
        - observed_at
      additionalProperties: false
      description: >-
        Probability: 0<=value<=1 and probability_event required. Expected
        payout: matching payout currency required. Conditional checks and
        numerical decimal comparison are server validation rules.
      allOf:
        - if:
            properties:
              value_type:
                const: PROBABILITY
          then:
            required:
              - probability_event
        - if:
            properties:
              value_type:
                const: EXPECTED_PAYOUT
          then:
            required:
              - currency
    FairValue:
      type: object
      properties:
        fair_value_id:
          type: string
          description: Opaque text identifier. Preserve its exact value.
          minLength: 1
        scope_id:
          type: string
          description: Opaque text identifier. Preserve its exact value.
          minLength: 1
        outcome_id:
          type: string
          minLength: 1
          description: Rook payout-side ID. YES and NO have separate IDs.
        market_version:
          type: string
          description: Opaque text identifier. Preserve its exact value.
          minLength: 1
        value_type:
          type: string
          enum:
            - PROBABILITY
            - EXPECTED_PAYOUT
        probability_event:
          anyOf:
            - type: string
              enum:
                - FULL_PAYOUT
            - type: 'null'
        value:
          $ref: '#/components/schemas/Decimal'
        currency:
          anyOf:
            - type: string
            - type: 'null'
        source:
          type: string
        observed_at:
          type: string
          format: date-time
        valid_until:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        updated_at:
          type: string
          format: date-time
        revision:
          type: string
          description: Opaque text identifier. Preserve its exact value.
          minLength: 1
        status:
          type: string
          enum:
            - CURRENT
            - EXPIRED
            - SUPERSEDED
      required:
        - fair_value_id
        - scope_id
        - outcome_id
        - market_version
        - value_type
        - value
        - source
        - observed_at
        - updated_at
        - revision
        - status
      additionalProperties: true
    Decimal:
      type: string
      description: >-
        Exact base-10 value encoded as a string; no exponent or non-finite
        values.
      pattern: ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      description: >-
        Proposed server-to-server API key. No client request HMAC signing scheme
        is specified.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.