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

# List scenarios

> Retrieve the possible settlement cases published for a Rook family. Supply family_id and scenario_version from /families; optionally select specific scenario_ids. Each item provides a scenario reference, readable label and description, plus how many underlying states it represents.

Pass the returned references unchanged to /payouts:calculate or use the family/version pin in /relationships:analyze and /evaluations:run. Scenario IDs only have meaning within their family and version. A wrong-family or stale reference fails explicitly. Pagination returns more columns from the same published catalog; it does not alter the scenario scope.

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


## OpenAPI

````yaml GET /scenarios
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:
  /scenarios:
    get:
      tags:
        - Families and scenarios
      summary: List scenarios
      description: >-
        Retrieve the possible settlement cases published for a Rook family.
        Supply family_id and scenario_version from /families; optionally select
        specific scenario_ids. Each item provides a scenario reference, readable
        label and description, plus how many underlying states it represents.


        Pass the returned references unchanged to /payouts:calculate or use the
        family/version pin in /relationships:analyze and /evaluations:run.
        Scenario IDs only have meaning within their family and version. A
        wrong-family or stale reference fails explicitly. Pagination returns
        more columns from the same published catalog; it does not alter the
        scenario scope.
      operationId: listScenarios
      parameters:
        - name: family_id
          in: query
          required: true
          description: >-
            Rook family ID connecting related markets across original venue
            events. Narrows the selection to this resource.
          schema:
            type: string
            description: Opaque text identifier. Preserve its exact value.
            minLength: 1
          example: fam_fed_dec_2026
        - name: scenario_version
          in: query
          required: true
          description: >-
            Published family scenario-catalog version. Use together with
            family_id to pin scenario meaning.
          schema:
            type: string
            description: Opaque text identifier. Preserve its exact value.
            minLength: 1
          example: '1'
        - name: scenario_ids
          in: query
          required: false
          description: >-
            Return only these scenario IDs within the required family and
            scenario_version. Repeat the parameter for multiple IDs.
          schema:
            type: array
            items:
              type: string
              description: Opaque text identifier. Preserve its exact value.
              minLength: 1
            minItems: 1
          style: form
          explode: true
        - name: page_size
          in: query
          required: false
          description: >-
            Requested maximum items; service caps disclosed by coverage.
            Oversize requests fail explicitly.
          schema:
            type: integer
            minimum: 1
            default: 50
        - name: page_token
          in: query
          required: false
          description: >-
            Opaque continuation; reuse the same filters/order. Cursor pins the
            original snapshot.
          schema:
            type: string
        - name: X-Client-Request-Id
          in: header
          required: false
          schema:
            type: string
          description: Caller correlation reference; not an idempotency guarantee.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListScenariosResponse'
              example:
                items:
                  - reference:
                      family_id: fam_fed_dec_2026
                      scenario_version: '1'
                      scenario_id: scn_cut
                    label: Rate cut
                    description: >-
                      The announced policy-rate target is lower than before the
                      decision.
                    representation: CUT_HOLD_HIKE
                    represented_state_count: 1
                  - reference:
                      family_id: fam_fed_dec_2026
                      scenario_version: '1'
                      scenario_id: scn_hold
                    label: Rate unchanged
                    description: The announced policy-rate target is unchanged.
                    representation: CUT_HOLD_HIKE
                    represented_state_count: 1
                  - reference:
                      family_id: fam_fed_dec_2026
                      scenario_version: '1'
                      scenario_id: scn_hike
                    label: Rate hike
                    description: >-
                      The announced policy-rate target is higher than before the
                      decision.
                    representation: CUT_HOLD_HIKE
                    represented_state_count: 1
                next_page_token: null
                snapshot_id: snap_rates_20261019_120000
                as_of: '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:
    ListScenariosResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Scenario'
        next_page_token:
          anyOf:
            - type: string
            - type: 'null'
        snapshot_id:
          type: string
          description: Opaque text identifier. Preserve its exact value.
          minLength: 1
        as_of:
          type: string
          format: date-time
      required:
        - items
        - next_page_token
        - snapshot_id
        - as_of
      additionalProperties: true
    Scenario:
      type: object
      properties:
        reference:
          $ref: '#/components/schemas/ScenarioRef'
        label:
          type: string
        description:
          type: string
        representation:
          type: string
        represented_state_count:
          type: integer
          minimum: 0
      required:
        - reference
        - label
        - description
        - representation
        - represented_state_count
      additionalProperties: true
      description: >-
        Human-readable settlement scenario; no internal variables, predicates or
        AST.
    ScenarioRef:
      type: object
      properties:
        family_id:
          type: string
          minLength: 1
          description: >-
            Rook family ID connecting related markets across original venue
            events.
        scenario_version:
          type: string
          description: Opaque text identifier. Preserve its exact value.
          minLength: 1
        scenario_id:
          type: string
          minLength: 1
          description: Rook scenario ID within its family and published scenario version.
      required:
        - family_id
        - scenario_version
        - scenario_id
      additionalProperties: false
  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.