> ## 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 families > Discover Rook's grouping of related markets across the events maintained by venues. A family sits above venue events and their markets; it does not replace the events or rewrite their source membership. Use family_id for one family, market_ids to find families containing supplied markets, or q to search by topic. Each item returns family_id, event_ids, market_ids, a readable description, analytical_coverage and available scenario versions. Event and market responses include family_ids so you can reach the same family from either starting point. Several memberships remain explicit rather than forcing an arbitrary exclusive tree. Use /events?family_id=... to browse its original venue events, /markets?family_id=... for member markets and /scenarios for a published scenario catalog. Membership describes the grouping; analytical_coverage states whether settlement analysis is available. Listing an event in a family does not claim that every market in that event has supported payout analysis. See the [integration guide](/guides/scenarios) for the workflow and interpretation of this response. ## Examples ```http Browse families theme={null} GET /v1/families ``` ```http Get one family theme={null} GET /v1/families?family_id=fam_fed_dec_2026 ``` ```http Search by words theme={null} GET /v1/families?q=Fed%20rate%20cut&page_size=5 ``` ```http Filter results theme={null} GET /v1/families?category=rates&page_size=20 ``` The response always contains `items`, `next_page_token`, `snapshot_id` and `as_of`. An ID lookup returns zero or one item with its full details. No match returns an empty `items` array. Use `q` to search titles, descriptions and tags by words. Results are ordered by relevance. `page_size` sets the maximum results per page; use `next_page_token` to continue. Other filters, such as `category` or `venue`, narrow the search. ## OpenAPI ````yaml GET /families 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: /families: get: tags: - Families and scenarios summary: List families description: >- Discover Rook's grouping of related markets across the events maintained by venues. A family sits above venue events and their markets; it does not replace the events or rewrite their source membership. Use family_id for one family, market_ids to find families containing supplied markets, or q to search by topic. Each item returns family_id, event_ids, market_ids, a readable description, analytical_coverage and available scenario versions. Event and market responses include family_ids so you can reach the same family from either starting point. Several memberships remain explicit rather than forcing an arbitrary exclusive tree. Use /events?family_id=... to browse its original venue events, /markets?family_id=... for member markets and /scenarios for a published scenario catalog. Membership describes the grouping; analytical_coverage states whether settlement analysis is available. Listing an event in a family does not claim that every market in that event has supported payout analysis. operationId: listFamilies parameters: - name: family_id in: query required: false description: >- Rook family ID connecting related markets across original venue events. Omit to browse. Exact lookup retains the items envelope. schema: type: string minLength: 1 example: fam_fed_dec_2026 - name: q in: query required: false description: >- Search titles, descriptions and tags by words, ignoring letter case. Results are ordered by relevance with stable ID tie-breaking. Other filters narrow the matches. schema: type: string minLength: 1 example: Fed rate cut - name: market_ids in: query required: false description: >- Rook market IDs in this resource. On an event these reflect its source venue membership; on a family they identify the related market members. schema: type: array items: type: string description: Opaque text identifier. Preserve its exact value. minLength: 1 minItems: 1 style: form explode: true - name: category in: query required: false description: >- Exact category label used by the catalog, for example rates. Narrows search results. schema: type: string - name: venue in: query required: false description: >- Venue identifier, such as polymarket or kalshi. Required when looking up a venue-native ID; never inferred from the ID. schema: type: string - 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/ListFamiliesResponse' example: items: - family_id: fam_fed_dec_2026 title: December 2026 Fed rate decision description: >- Related markets across two distinct illustrative Polymarket events. Original event membership is preserved; the family connects the cut and hold markets. market_ids: - mkt_fed_dec_2026_cut - mkt_fed_dec_2026_hold current_scenario_version: '1' scenario_versions: - '1' supported_convention_ids: - demo_all_legs_win_v1 analytical_coverage: COMPLETE observed_at: '2026-10-19T12:00:00Z' event_ids: - evt_pm_900001 - evt_pm_900002 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: ListFamiliesResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/Family' 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 Family: type: object properties: family_id: type: string minLength: 1 description: >- Rook family ID connecting related markets across original venue events. title: type: string description: type: string market_ids: type: array items: type: string description: Opaque text identifier. Preserve its exact value. minLength: 1 description: >- Rook market IDs in this resource. On an event these reflect its source venue membership; on a family they identify the related market members. current_scenario_version: anyOf: - type: string description: Opaque text identifier. Preserve its exact value. minLength: 1 - type: 'null' scenario_versions: type: array items: type: string description: Opaque text identifier. Preserve its exact value. minLength: 1 supported_convention_ids: type: array items: type: string description: Opaque text identifier. Preserve its exact value. minLength: 1 analytical_coverage: type: string enum: - COMPLETE - PARTIAL - UNAVAILABLE observed_at: type: string format: date-time event_ids: type: array items: type: string description: >- Rook ID for one original venue event. Its identity is scoped to venue and venue_event_id; related events remain separate. minLength: 1 description: >- Rook IDs of the original venue events containing these markets or listings. Family membership never rewrites event membership. required: - family_id - title - event_ids - market_ids - current_scenario_version - scenario_versions - analytical_coverage - observed_at additionalProperties: true description: >- Rook grouping above original venue events and their related markets. event_ids and market_ids expose membership; analytical_coverage separately reports support. Source events remain unchanged and resources may carry several family references. 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.