openapi: 3.0.3
info:
  title: BOPTEST Service API
  description: A REST API for emulating buildings for testing control systems.
  version: 0.8.0
servers:
  - url: http://localhost
    description: Local server
  - url: http://api.boptest.net
    description: NREL BOPTEST Service
components:
  schemas:
    BoundedSignalMeta:
      type: object
      properties:
        Description:
          type: string
          description: Description of the signal.
        Maximum:
          type: number
          nullable: true
          description: Maximum value of the signal.
        Minimum:
          type: number
          nullable: true
          description: Minimum value of the signal.
        Unit:
          type: string
          nullable: true
          description: Unit of the signal.
    SignalMeta:
      type: object
      properties:
        Description:
          type: string
          description: Description of the signal.
        Unit:
          type: string
          nullable: true
          description: Unit of the signal.
    BoundedSignalMetaResponse:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/BoundedSignalMeta'
    SignalMetaResponse:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/SignalMeta'
    ForecastQuery:
      type: object
      properties:
        point_names:
          type: array
          items:
            type: string
          description: List of point names.
        horizon:
          type: number
          description: Forecast horizon in seconds.
        interval:
          type: number
          description: Time interval between forecast points in seconds.
    ResultsQuery:
      type: object
      properties:
        point_names:
          type: array
          items:
            type: string
          description: List of point names.
        start_time:
          type: number
          description: Start time of the results query (epoch time).
        final_time:
          type: number
          description: Final time of the results query (epoch time).
    TimeSeries:
      type: object
      additionalProperties:
        type: array
        items:
          type: number
    StandardResponse:
      type: object
      properties:
        message:
          type: string
          description: A message describing the response.
        payload:
          type: object
          description: The response payload.
        status:
          type: integer
          description: HTTP status code.
  parameters:
    TestId:
      name: testid
      in: path
      required: true
      description: The UUID of the test case.
      schema:
        type: string
paths:
  /inputs/{testid}:
    parameters:
      - $ref: '#/components/parameters/TestId'
    get:
      summary: Get metadata for inputs
      description: Returns metadata for input signals.
      responses:
        '200':
          description: Successful response with metadata for inputs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Metadata for inputs retrieved successfully."
                  payload:
                    $ref: '#/components/schemas/BoundedSignalMetaResponse'
                  status:
                    type: integer
                    example: 200
  /measurements/{testid}:
    parameters:
      - $ref: '#/components/parameters/TestId'
    get:
      summary: Get metadata for measurements
      description: Returns metadata for measurement signals.
      responses:
        '200':
          description: Successful response with metadata for measurements.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Metadata for measurements retrieved successfully."
                  payload:
                    $ref: '#/components/schemas/BoundedSignalMetaResponse'
                  status:
                    type: integer
                    example: 200
  /forecast_points/{testid}:
    parameters:
      - $ref: '#/components/parameters/TestId'
    get:
      summary: Get metadata for forecast points
      description: Returns metadata for forecast point signals.
      responses:
        '200':
          description: Successful response with metadata for forecast points.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Metadata for forecast points retrieved successfully."
                  payload:
                    $ref: '#/components/schemas/SignalMetaResponse'
                  status:
                    type: integer
                    example: 200
  /forecast/{testid}:
    parameters:
      - $ref: '#/components/parameters/TestId'
    put:
      summary: Submit a forecast query
      description: Sends a ForecastQuery payload and returns a TimeSeries response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForecastQuery'
      responses:
        '200':
          description: Successful response with forecast time series.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Forecast query processed successfully."
                  payload:
                    $ref: '#/components/schemas/TimeSeries'
                  status:
                    type: integer
                    example: 200
  /results/{testid}:
    parameters:
      - $ref: '#/components/parameters/TestId'
    put:
      summary: Submit a results query
      description: Sends a ResultsQuery payload and returns a TimeSeries response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResultsQuery'
      responses:
        '200':
          description: Successful response with results time series.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Results query processed successfully."
                  payload:
                    $ref: '#/components/schemas/TimeSeries'
                  status:
                    type: integer
                    example: 200
  /advance/{testid}:
    parameters:
      - $ref: '#/components/parameters/TestId'
    post:
      summary: Advance the simulation
      description: Advances the simulation with optional input overwrites. The payload can include input values and activation flags for overwriting.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                oneOf:
                  - type: number
                    description: Input value to overwrite.
                  - type: integer
                    enum: [0, 1]
                    description: Activation flag (1 to enable overwrite, 0 to disable).
      responses:
        '200':
          description: Successful response with simulation advancement results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Simulation advanced successfully."
                  payload:
                    type: object
                    additionalProperties:
                      type: number
                      description: Resulting values after advancing the simulation.
                  status:
                    type: integer
                    example: 200
  /name/{testid}:
    parameters:
      - $ref: '#/components/parameters/TestId'
    get:
      summary: Get the test case name
      description: Returns the loaded test case name.
      responses:
        '200':
          description: Successful response with the test case name.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Queried the name of the test case successfully."
                  payload:
                    type: object
                    properties:
                      name:
                        type: string
                        description: The name of the test case.
                    description: The payload containing the test case name.
                  status:
                    type: integer
                    example: 200
  /step/{testid}:
    parameters:
      - $ref: '#/components/parameters/TestId'
    get:
      summary: Get the simulation time step
      description: Returns the time step used in the simulation.
      responses:
        '200':
          description: Successful response with the time step.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Simulation time step retrieved successfully."
                  payload:
                    type: number
                    description: The time step used in the simulation.
                  status:
                    type: integer
                    example: 200
    put:
      summary: Set the simulation time step
      description: Sets the time step used in the simulation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                step:
                  type: number
                  description: The new time step to set for the simulation.
      responses:
        '200':
          description: Successful response indicating the time step was updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Simulation time step updated successfully."
                  payload:
                    type: string
                    description: Confirmation message.
                  status:
                    type: integer
                    example: 200
  /scenario/{testid}:
    parameters:
      - $ref: '#/components/parameters/TestId'
    get:
      summary: Get the current scenario description
      description: Returns a description of the current scenario.
      responses:
        '200':
          description: Successful response with the scenario description.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Scenario description retrieved successfully."
                  payload:
                    type: object
                    additionalProperties:
                      type: string
                      description: Key-value pairs describing the current scenario.
                  status:
                    type: integer
                    example: 200
  /kpi/{testid}:
    parameters:
      - $ref: '#/components/parameters/TestId'
    get:
      summary: Get the Key Performance Indicators (KPIs)
      description: Returns the KPIs as calculated by the emulator.
      responses:
        '200':
          description: Successful response with the KPIs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "KPIs retrieved successfully."
                  payload:
                    type: object
                    additionalProperties:
                      type: number
                      description: Key-value pairs of KPI names and their values.
                  status:
                    type: integer
                    example: 200
  /initialize/{testid}:
    parameters:
      - $ref: '#/components/parameters/TestId'
    put:
      summary: Initialize the simulation
      description: Initializes the simulation with a start time and warmup period.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start_time:
                  type: number
                  description: The start time of the simulation (epoch time).
                warmup_period:
                  type: number
                  description: The warmup period for the simulation in seconds.
      responses:
        '200':
          description: Successful response indicating the simulation was initialized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Simulation initialized successfully."
                  payload:
                    type: string
                    description: Confirmation message.
                  status:
                    type: integer
                    example: 200