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

# List rooms with their latest runs

> Every room with its readiness check (the routine, its own or the customer default, and when it runs) and its latest power and readiness runs, so one call answers "is every room ready this morning?". A latest run is null for a room that hasn't had one. Not paginated. Requires the `nightly.view` scope.

Updated 23 Oct 2026 15:20 · page c480a5c


## OpenAPI

````yaml api-reference/openapi.json GET /pub/v1/room-readiness/rooms
openapi: 3.1.0
info:
  title: M.A.R.C.U.S. Public API
  version: 1.0.0
  summary: Programmatic access to a customer's AV fleet.
  description: >-
    Read-only integration API for the M.A.R.C.U.S. monitoring platform. Use it
    to sync device inventory into a CMDB, mirror alerts into an incident tool,
    or feed dashboards with live fleet state. Every route is scoped to the
    token's tenant — one token, one customer's data.


    Polling once a minute is ample for most use cases. Cursor-based pagination
    keeps list endpoints stable under concurrent inserts.
servers:
  - url: https://api.uat.involvecloud.com
    description: UAT
  - url: https://api.involvecloud.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Meta
    description: Health and identity of the calling token.
  - name: Devices
    description: >-
      AV endpoints under management — displays, cameras, DSPs, control
      processors.
  - name: Firmware
    description: >-
      Firmware versions across the fleet, against the targets set on the
      Firmware page. Needs the view.firmware scope.
  - name: Hierarchy
    description: 'Physical structure: buildings and rooms.'
  - name: Assets
    description: >-
      The CMDB inventory — every physical thing the tenant owns, monitored or
      not. Broader than Devices: includes mounts, cables, spares, retired gear.
  - name: Alerts
    description: Open + historical incidents raised on devices and collectors.
  - name: Events
    description: Device-emitted events — state changes, adapter messages, telemetry deltas.
  - name: Audit
    description: >-
      The tenant's audit trail of changes and commands. Needs the view.audit
      scope.
  - name: Room Readiness
    description: >-
      Results of each room's power schedule (switched off at night, on in the
      morning) and readiness checks (a test routine, down to every step). Needs
      the nightly.view scope.
paths:
  /pub/v1/room-readiness/rooms:
    get:
      tags:
        - Room Readiness
      summary: List rooms with their latest runs
      description: >-
        Every room with its readiness check (the routine, its own or the
        customer default, and when it runs) and its latest power and readiness
        runs, so one call answers "is every room ready this morning?". A latest
        run is null for a room that hasn't had one. Not paginated. Requires the
        `nightly.view` scope.
      responses:
        '200':
          description: Rooms, ordered by building then room.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReadinessRoom'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    ReadinessRoom:
      type: object
      required:
        - room_id
        - room
        - building_id
        - building
      properties:
        room_id:
          type: string
          format: uuid
        room:
          type: string
        building_id:
          type: string
          format: uuid
        building:
          type: string
        routine_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            The room's readiness routine (its own, or the customer default);
            null when the room isn't checked.
        routine:
          type:
            - string
            - 'null'
        readiness_time:
          type:
            - string
            - 'null'
          description: >-
            When the readiness check runs, HH:MM in the customer's timezone;
            null when the room isn't checked.
        excluded_until:
          type:
            - string
            - 'null'
          format: date
          description: >-
            The room is left out of both the power schedule and readiness checks
            up to and including this date.
        latest_run:
          oneOf:
            - $ref: '#/components/schemas/ReadinessRun'
            - type: 'null'
          description: The more recent of the two below.
        latest_power_run:
          oneOf:
            - $ref: '#/components/schemas/ReadinessRun'
            - type: 'null'
        latest_readiness_run:
          oneOf:
            - $ref: '#/components/schemas/ReadinessRun'
            - type: 'null'
    ReadinessRun:
      type: object
      required:
        - id
        - kind
        - room_id
        - room
        - building_id
        - building
        - status
        - phase
        - scheduled_at
        - steps_total
        - steps_passed
        - steps_failed
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
            - power
            - readiness
          description: >-
            `power`: the room switched off at night and back on. `readiness`: a
            test routine.
        room_id:
          type: string
          format: uuid
        room:
          type: string
        building_id:
          type: string
          format: uuid
        building:
          type: string
        routine_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The test routine the run used; null for a power-cycle-only run.
        routine:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - pending
            - in_progress
            - succeeded
            - failed
            - skipped
        phase:
          type: string
          enum:
            - pending
            - scheduled_off
            - 'off'
            - scheduled_on
            - waking
            - warming
            - testing
            - ready
            - failed
          description: How far the run got. `ready` means the room passed.
        scheduled_at:
          type: string
          format: date-time
        started_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the run began: the evening power-off, or the start of a run
            without a power cycle.
        powered_on_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the morning power-on began; null until then, and for runs
            without a power cycle.
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
        duration_seconds:
          type:
            - integer
            - 'null'
          description: >-
            How long the room took to be ready (or to fail) after power-on; for
            a run without a power cycle, from its start.
        failure_reason:
          type:
            - string
            - 'null'
        steps_total:
          type: integer
          description: >-
            Steps recorded so far, including the scheduled power off and power
            on.
        steps_passed:
          type: integer
        steps_failed:
          type: integer
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - code
          properties:
            message:
              type: string
              description: Human-readable summary. Not intended for parsing.
            code:
              type: string
              enum:
                - bad_request
                - unauthorized
                - forbidden
                - not_found
                - internal_error
                - error
              description: Stable machine-readable identifier.
      example:
        error:
          message: 'token missing scope: view.dashboard'
          code: forbidden
  responses:
    Unauthorized:
      description: Missing, malformed, revoked, or expired bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Token authenticated but doesn't hold the scope this endpoint requires.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: avb_<prefix>_<secret>
      description: >-
        Mint a token from the portal at Settings → API tokens. Send it as
        `Authorization: Bearer avb_...` on every request. Query-string tokens
        are NOT accepted — the URL ends up in access logs.

````

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