openapi: 3.1.0
info:
  title: Steelcase RoomWizard API
  description: >-
    The Steelcase RoomWizard API provides programmatic access to conference
    room scheduling and reservation management. Using HTTP GET and POST
    requests, developers can retrieve room bookings, create reservations,
    check room availability, and manage meeting information. The API supports
    integration with enterprise calendaring systems including Microsoft
    Exchange, Office 365, and Google Calendar via the RoomWizard connector.
    The API is hosted on the local network where the RoomWizard connector
    is installed.
  version: '1.0.0'
  contact:
    name: Steelcase Tech Support
    url: https://www.steelcase.com/techsupport/
  termsOfService: https://www.steelcase.com/
externalDocs:
  description: Steelcase Tech Support
  url: https://www.steelcase.com/techsupport/
servers:
  - url: https://{host}:{port}/api
    description: RoomWizard Connector Server (local network)
    variables:
      host:
        default: roomwizard.local
        description: Hostname or IP address of the RoomWizard connector server.
      port:
        default: '443'
        description: Port of the RoomWizard connector server.
tags:
  - name: Bookings
    description: >-
      Manage conference room reservations including creating, retrieving,
      updating, and cancelling bookings.
  - name: Rooms
    description: >-
      Retrieve room information including availability, capacity, and
      equipment details.
  - name: Status
    description: >-
      Monitor the connectivity and health status of RoomWizard devices
      and the connector service.
paths:
  /get_bookings:
    get:
      operationId: getBookings
      summary: Get Room Bookings
      description: >-
        Retrieves a list of bookings for a specific room or date range.
        Returns meeting details including subject, organizer, start time,
        end time, and attendee count.
      tags:
        - Bookings
      parameters:
        - name: room_id
          in: query
          required: false
          schema:
            type: string
          description: Filter bookings by room identifier.
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Start date for booking query (YYYY-MM-DD).
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: End date for booking query (YYYY-MM-DD).
        - name: include_cancelled
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Whether to include cancelled bookings in the response.
      responses:
        '200':
          description: List of room bookings
          content:
            application/json:
              schema:
                type: object
                properties:
                  bookings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Booking'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'
  /get_availability:
    get:
      operationId: getRoomAvailability
      summary: Get Room Availability
      description: >-
        Retrieves the availability status of one or more rooms for a
        given time range, showing free/busy slots and current occupancy.
      tags:
        - Rooms
      parameters:
        - name: room_id
          in: query
          required: false
          schema:
            type: string
          description: Specific room ID to check. If omitted, returns all rooms.
        - name: start_time
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start of the availability window (ISO 8601 format).
        - name: end_time
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End of the availability window (ISO 8601 format).
      responses:
        '200':
          description: Room availability data
          content:
            application/json:
              schema:
                type: object
                properties:
                  rooms:
                    type: array
                    items:
                      $ref: '#/components/schemas/RoomAvailability'
        '400':
          $ref: '#/components/responses/BadRequest'
  /create_booking:
    post:
      operationId: createBooking
      summary: Create a Booking
      description: >-
        Creates a new conference room booking for the specified room and
        time slot. The booking is synchronized with the connected
        calendaring system (Exchange, Office 365, or Google Calendar).
      tags:
        - Bookings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingCreate'
      responses:
        '201':
          description: Booking created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: Room already booked for the requested time slot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cancel_booking:
    post:
      operationId: cancelBooking
      summary: Cancel a Booking
      description: >-
        Cancels an existing conference room booking. The cancellation is
        propagated to the connected calendaring system.
      tags:
        - Bookings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - booking_id
              properties:
                booking_id:
                  type: string
                  description: The unique identifier of the booking to cancel.
                reason:
                  type: string
                  description: Optional reason for cancellation.
      responses:
        '200':
          description: Booking cancelled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /get_rooms:
    get:
      operationId: listRooms
      summary: List Rooms
      description: >-
        Returns a list of all conference rooms managed by the RoomWizard
        system including room names, capacity, equipment, and location.
      tags:
        - Rooms
      parameters:
        - name: building
          in: query
          required: false
          schema:
            type: string
          description: Filter rooms by building name or ID.
        - name: floor
          in: query
          required: false
          schema:
            type: string
          description: Filter rooms by floor.
        - name: min_capacity
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
          description: Minimum room capacity required.
      responses:
        '200':
          description: List of rooms
          content:
            application/json:
              schema:
                type: object
                properties:
                  rooms:
                    type: array
                    items:
                      $ref: '#/components/schemas/Room'
  /get_room:
    get:
      operationId: getRoom
      summary: Get Room Details
      description: >-
        Returns detailed information about a specific RoomWizard-managed
        conference room including current status, capacity, and amenities.
      tags:
        - Rooms
      parameters:
        - name: room_id
          in: query
          required: true
          schema:
            type: string
          description: The unique identifier of the room.
      responses:
        '200':
          description: Room details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Room'
        '404':
          $ref: '#/components/responses/NotFound'
  /status:
    get:
      operationId: getConnectorStatus
      summary: Get Connector Status
      description: >-
        Returns the health and connectivity status of the RoomWizard
        connector service and all registered devices.
      tags:
        - Status
      responses:
        '200':
          description: Connector status information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorStatus'
components:
  schemas:
    Booking:
      type: object
      description: A conference room booking.
      properties:
        booking_id:
          type: string
          description: Unique identifier for the booking.
        room_id:
          type: string
          description: ID of the booked room.
        room_name:
          type: string
          description: Name of the booked room.
        subject:
          type: string
          description: Meeting subject/title.
        organizer:
          type: string
          description: Meeting organizer name or email.
        start_time:
          type: string
          format: date-time
          description: Meeting start time (ISO 8601).
        end_time:
          type: string
          format: date-time
          description: Meeting end time (ISO 8601).
        attendee_count:
          type: integer
          description: Number of expected attendees.
        status:
          type: string
          enum:
            - confirmed
            - cancelled
            - in-progress
            - completed
          description: Current booking status.
        calendar_source:
          type: string
          enum:
            - exchange
            - office365
            - google
            - local
          description: The calendaring system this booking is synchronized with.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the booking was created.
    BookingCreate:
      type: object
      required:
        - room_id
        - subject
        - start_time
        - end_time
      description: Request body for creating a new booking.
      properties:
        room_id:
          type: string
          description: ID of the room to book.
        subject:
          type: string
          description: Meeting subject/title.
        organizer:
          type: string
          description: Meeting organizer name or email.
        start_time:
          type: string
          format: date-time
          description: Meeting start time (ISO 8601).
        end_time:
          type: string
          format: date-time
          description: Meeting end time (ISO 8601).
        attendee_count:
          type: integer
          minimum: 1
          description: Number of expected attendees.
        notes:
          type: string
          description: Optional meeting notes.
    Room:
      type: object
      description: A conference room managed by RoomWizard.
      properties:
        room_id:
          type: string
          description: Unique identifier for the room.
        name:
          type: string
          description: Room name.
        building:
          type: string
          description: Building where the room is located.
        floor:
          type: string
          description: Floor where the room is located.
        capacity:
          type: integer
          description: Maximum room capacity.
        is_available:
          type: boolean
          description: Whether the room is currently available.
        equipment:
          type: array
          items:
            type: string
          description: List of available equipment (e.g., projector, whiteboard, video conferencing).
        email_address:
          type: string
          format: email
          description: Room calendar email address for direct calendar invites.
    RoomAvailability:
      type: object
      description: Availability information for a room during a time window.
      properties:
        room_id:
          type: string
          description: Room identifier.
        room_name:
          type: string
          description: Room name.
        is_available_now:
          type: boolean
          description: Whether the room is currently available.
        next_available:
          type: string
          format: date-time
          description: Next available time slot start.
        busy_slots:
          type: array
          items:
            type: object
            properties:
              start_time:
                type: string
                format: date-time
              end_time:
                type: string
                format: date-time
          description: List of busy time slots within the queried window.
    ConnectorStatus:
      type: object
      description: Health status of the RoomWizard connector.
      properties:
        status:
          type: string
          enum:
            - healthy
            - degraded
            - offline
          description: Overall connector health status.
        calendar_connected:
          type: boolean
          description: Whether the connector is connected to the calendaring system.
        calendar_type:
          type: string
          description: Type of calendar system connected (exchange, office365, google).
        device_count:
          type: integer
          description: Number of RoomWizard devices registered.
        devices_online:
          type: integer
          description: Number of devices currently online.
        last_sync:
          type: string
          format: date-time
          description: Timestamp of the last successful calendar synchronization.
    Error:
      type: object
      description: An error response.
      properties:
        error:
          type: string
          description: Error code.
        message:
          type: string
          description: Human-readable error message.
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'