Aedifion Analytics API

openapi: 3.2.0
info:
  description: 'Welcome to the interactive user interface (UI) for the aedifion REST API.


    This UI allows you to


    - browse documentation of all endpoints

    - explore schemas and examples of request parameters and responses

    - call endpoints and view responses


    Further documentation as well as extensive guides and tutorials are available in the official documentation.'
  title: Docs Analytics API
  version: ''
servers:
- url: ''
tags:
- description: Creating, modifying, and accessing analytics and related resources.
  name: Analytics
paths:
  /v2/analytics/componentInProject/{componentinproject_id}/results:
    get:
      description: Returns detailed information of a component containing analysis results and a list of result ids associated to it.
      operationId: get_component_results
      parameters:
      - description: '[mandatory] The id of the component in project.'
        in: path
        name: componentinproject_id
        required: true
        schema:
          format: int64
          type: integer
      - description: '[mandatory] The id of the project.'
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - $ref: '#/components/parameters/LanguageQueryParam'
      - description: 'The optional system of units in which the analysis results should be returned (Example: **metric**).

          Request the **GET /v2/labels/systems** endpoint to fetch available units systems.

          '
        in: query
        name: units_system
        schema:
          type: string
      - description: 'The optional currency system in which the analysis results should be returned (Example: **EUR**).

          Request the **GET /v2/labels/systems** endpoint to fetch available currency systems.

          '
        in: query
        name: currency_system
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsResultsForComponent'
          description: Success
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get analysis result references for a component
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
  /v2/analytics/components/kpi_aggregation:
    get:
      description: Returns aggregated KPI results for components.
      operationId: get_components_kpi_aggregation
      parameters:
      - description: '[mandatory] The id of the project.'
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: '[mandatory] The list of component ids.'
        in: query
        name: component_ids
        required: true
        schema:
          items:
            format: int64
            type: integer
          type: array
      - description: The list of KPI identifiers to limit the result.
        in: query
        name: kpi_identifiers
        required: false
        schema:
          items:
            type: string
          type: array
      - description: The start time of the aggregation interval. It defaults to the current timestamp minus one year.
        in: query
        name: start
        required: false
        schema:
          format: date-time
          type: string
      - description: The end time of the aggregation interval. It defaults to the current timestamp.
        in: query
        name: end
        required: false
        schema:
          format: date-time
          type: string
      - description: 'Components in projects can be filtered by their attributes.

          Format must be in the form of key=value.

          Multiple filters can be applied, separated by a '';'' like: key=value; key2=value

          Filters with same key will be processed as ''Or'' and ''And'' across different keys.

          Note that attribute keys are seen as suffixes. TODO: Improve this text.

          '
        in: query
        name: attribute_filter
        schema:
          type: string
      - description: 'The optional system of units in which the KPI aggregation results should be returned (Example: **metric**).

          Request the **GET /v2/labels/systems** endpoint to fetch available units systems.

          '
        in: query
        name: units_system
        schema:
          type: string
      - description: 'The optional currency system in which the KPI aggregation results should be returned (Example: **EUR**).

          Request the **GET /v2/labels/systems** endpoint to fetch available currency systems.

          '
        in: query
        name: currency_system
        schema:
          type: string
      - description: "Desired aggregation method to be used for aggregating KPI results of a project over the given time interval.\nDefault method: \"mean\"\nAvailable options:\n - \"max\"\n - \"mean\"\n - \"min\"\n - \"sum\"\n - \"latest_execution\"\n"
        in: query
        name: time_aggregation
        required: false
        schema:
          default: mean
          enum:
          - max
          - mean
          - min
          - sum
          - latest_execution
          type: string
      - description: "Desired aggregation method to be used for aggregating the aggregated KPI results of projects.\nDefault method: \"mean\"\nAvailable options:\n - \"max\"\n - \"mean\"\n - \"min\"\n - \"sum\"\n"
        in: query
        name: component_aggregation
        required: false
        schema:
          default: mean
          enum:
          - max
          - mean
          - min
          - sum
          type: string
      - $ref: '#/components/parameters/LanguageQueryParam'
      - description: Page number.
        in: query
        name: page
        schema:
          format: int64
          type: integer
      - description: Items per page. Defaults to 20, maximum limit is 100.
        in: query
        name: per_page
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentsKPIAggregationResult'
          description: Success
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get aggregated KPI results for components
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
  /v2/analytics/componentsInProject:
    get:
      description: 'Returns a list of components in a project including their corresponding signal-color.

        **Note** that `"signal_color": "grey"` indicates, that a component does not have results yet.'
      operationId: get_analysis_components
      parameters:
      - description: '[mandatory] The id of the project.'
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: Page number.
        in: query
        name: page
        required: false
        schema:
          format: int64
          type: integer
      - description: Items per page. Defaults to 20, maximum limit is 100.
        in: query
        name: per_page
        required: false
        schema:
          format: int64
          type: integer
      - $ref: '#/components/parameters/LanguageQueryParam'
      - description: 'Optional parameter, filter on the name of the component in the project.

          You can also search by the component type, translated into the chosen language,

          e.g. "boiler" with language "en" or "Kessel" with language "de".

          '
        in: query
        name: search
        required: false
        schema:
          type: string
      - description: 'Results can be filtered by keys: alphanumeric_id, signal_color and status.

          alphanumeric_id refers to the corresponding components.

          signal_color can be one of: red, yellow, green, grey

          status can be one of: Success., Failed., Processing.

          Format must be in the form of key=value.

          Multiple filters can be applied, separated by a '';'' like: key=value; key2=value

          Filters with same key will be processed as ''Or'' and ''And'' across different keys.

          '
        in: query
        name: filter
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsResultsForComponents'
          description: Success
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get components in a project with signal color
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
  /v2/analytics/functions:
    get:
      description: Returns a list of available analysis functions. If a component name or id is passed, functions are filtered for the component.
      operationId: get_analysis_functions
      parameters:
      - description: Filter functions by component alphanumeric id.
        in: query
        name: component_alphanumeric_id
        required: false
        schema:
          type: string
      - description: Filter functions by component id.
        in: query
        name: component_id
        required: false
        schema:
          format: int64
          type: integer
      - $ref: '#/components/parameters/LanguageQueryParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/AnalysisFunction'
                type: array
          description: Success
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get a list of available analysis functions
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
  /v2/analytics/instance:
    post:
      description: Creates an analysis config instance for a component in a project.
      operationId: post_analysis_instance
      parameters:
      - description: '[mandatory] The id of the project.'
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewInstanceConfig'
        description: '[mandatory] The anaylsis config.'
        required: true
        x-body-name: instance_config
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceConfig'
          description: Success
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Create an analysis instance
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
  /v2/analytics/instance/{instance_id}:
    delete:
      description: Deletes an analysis instance configured in a project.
      operationId: delete_analysis_instance
      parameters:
      - description: '[mandatory] The id of the project.'
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: '[mandatory] The id of the instance.'
        in: path
        name: instance_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The deleted instance is returned in the ''resource'' field and the ''operation'' is set to ''delete''.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unsuccessful request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''delete''."

            '
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Delete an analysis instance configured in a project
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
    get:
      description: Returns details of an analysis instance configured in a project.
      operationId: get_analysis_instance
      parameters:
      - description: '[mandatory] The id of the project.'
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: '[mandatory] The id of the instance.'
        in: path
        name: instance_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceConfig'
          description: Success
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unsuccessful request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''get''.

            '
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get a detailed analysis instance
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
    put:
      description: Updates an analysis instance.
      operationId: put_analysis_instance
      parameters:
      - description: '[mandatory] The id of the project.'
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: '[mandatory] The id of the instance.'
        in: path
        name: instance_id
        required: true
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInstanceConfig'
        description: '[mandatory] The anaylsis config.'
        required: true
        x-body-name: instance_config
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceConfig'
          description: Success
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Update an analysis instance
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
  /v2/analytics/instance/{instance_id}/result/{result_id}:
    get:
      description: 'Returns the result of an executed instance referenced by its result_id.


        aedifion.io and any add-ons do not include energy consulting. All data calculated, analysed and/or displayed by aedifion.io and any add-ons, especially setting values (e.g. room temperature) or the mappings of datapoints, are non-binding recommendations that have to be carefully checked by the user''s qualified personnel in each individual case before implementation ("human-in-the-loop principle").'
      operationId: get_instance_result
      parameters:
      - description: The id of the project.
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: The id of the instance.
        in: path
        name: instance_id
        required: true
        schema:
          format: int64
          type: integer
      - description: result id to the executed instance.
        in: path
        name: result_id
        required: true
        schema:
          type: string
      - description: 'Choose language in which the results should be displayed.

          -  ''en'' for English

          -  ''de'' for German.

          '
        in: query
        name: result_language
        required: false
        schema:
          enum:
          - en
          - de
          type: string
      - description: 'The optional system of units in which the analysis results should be returned (Example: **metric**).

          Request the **GET /v2/labels/systems** endpoint to fetch available units systems.

          '
        in: query
        name: units_system
        schema:
          type: string
      - description: 'The optional currency system in which the analysis results should be returned (Example: **EUR**).

          Request the **GET /v2/labels/systems** endpoint to fetch available currency systems.

          '
        in: query
        name: currency_system
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisResult'
          description: Success
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get the result of an executed instance
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
  /v2/analytics/instance/{instance_id}/results:
    get:
      description: Returns a list of executions for an instance.
      operationId: get_instance_results
      parameters:
      - description: The id of the project.
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: The id of the instance.
        in: path
        name: instance_id
        required: true
        schema:
          format: int64
          type: integer
      - description: 'Choose language in which the interpretations should be displayed.

          -  ''en'' for English

          -  ''de'' for German.

          '
        in: query
        name: result_language
        required: false
        schema:
          enum:
          - en
          - de
          type: string
      - description: 'The optional system of units in which the analysis results should be returned (Example: **metric**).

          Request the **GET /v2/labels/systems** endpoint to fetch available units systems.

          '
        in: query
        name: units_system
        schema:
          type: string
      - description: 'The optional currency system in which the analysis results should be returned (Example: **EUR**).

          Request the **GET /v2/labels/systems** endpoint to fetch available currency systems.

          '
        in: query
        name: currency_system
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/AnalysisResultSummary'
                type: array
          description: Success
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get list of executions for an analysis instance
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
  /v2/analytics/instance/{instance_id}/run:
    post:
      description: Runs the analysis instance and returns a result_id which can be used to retrieve the result of the execution.
      operationId: post_analysis_instance_run
      parameters:
      - description: '[mandatory] The id of the project.'
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: '[mandatory] The id of the instance.'
        in: path
        name: instance_id
        required: true
        schema:
          format: int64
          type: integer
      - description: '[mandatory] The start timestamp of the interval analysed.'
        in: query
        name: start
        required: true
        schema:
          format: date-time
          type: string
      - description: '[mandatory] The end timestamp of the interval analysed.'
        in: query
        name: end
        required: true
        schema:
          format: date-time
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Run an analysis instance
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
  /v2/analytics/instances:
    get:
      description: Returns details of all analysis config instances configured in a project.
      operationId: get_analysis_instances
      parameters:
      - description: '[mandatory] The id of the project.'
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/InstanceConfig'
                type: array
          description: Success
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get details of all analysis instances
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
  /v2/analytics/instances/run:
    post:
      description: 'Runs multiple analysis instances in batch for calculated execution periods based on their execution schedules.

        The execution periods are calculated based on the execution_schedule of each analysis function:

        - Monthly: Always 1st of month to 1st of next month in UTC

        - Weekly: Always Monday to Monday in project timezone'
      operationId: post_analytics_instances_run
      parameters:
      - description: '[mandatory] The id of the project.'
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: '[mandatory] List of instance IDs to execute.'
        in: query
        name: instance_ids
        required: true
        schema:
          items:
            format: int64
            type: integer
          type: array
      - description: '[mandatory] The start timestamp of the date range for calculating execution periods.'
        in: query
        name: start
        required: true
        schema:
          format: date-time
          type: string
      - description: '[optional] The end timestamp of the date range. If not provided, defaults to current date.'
        in: query
        name: end
        required: false
        schema:
          format: date-time
          type: string
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: Success. All instances were found and started successfully. Returns list of created result IDs.
        '207':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Success'
                - properties:
                    resource:
                      $ref: '#/components/schemas/AnalyticsInstancesRunResponse'
                  type: object
          description: 'Multi-Status.

            Some instances were not found or some analyses failed to run.

            Returns list of created result IDs and list of instance IDs not found.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Run analysis instances in batch
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
  /v2/analytics/instances/scheduled/run:
    post:
      description: 'Runs all scheduled analysis instances of a project for calculated execution periods based on their execution schedules.

        The execution periods are calculated based on the execution_schedule of each analysis function:

        - Monthly: Always 1st of month to 1st of next month in UTC

        - Weekly: Always Monday to Monday in project timezone'
      operationId: post_analytics_scheduled_instances_run
      parameters:
      - description: '[mandatory] The ID of the project.'
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: Execution schedule of the instances. Defaults to all.
        in: query
        name: execution_schedule
        required: true
        schema:
          default: all
          enum:
          - all
          - weekly
          - monthly
          type: string
      - description: '[mandatory] The start timestamp of the date range for calculating execution periods.'
        in: query
        name: start
        required: true
        schema:
          format: date-time
          type: string
      - description: '[optional] The end timestamp of the date range. If not provided, defaults to current UTC datetime.'
        in: query
        name: end
        required: false
        schema:
          format: date-time
          type: string
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: Success. All scheduled instances started successfully. Returns list of created result IDs.
        '207':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Success'
                - properties:
                    resource:
                      $ref: '#/components/schemas/AnalysisResultReferences'
                  type: object
          description: 'Multi-Status.

            Some instances were already running.

            Returns list of created result IDs and a warning message if instances are already running.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Run all scheduled analysis instances of a project
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
  /v2/analytics/kpi:
    post:
      description: 'Creates a KPI for a component.

        If a KPI with the same type and identifier already exists, it will be updated.

        Manually created KPIs supersede KPIs generated by .analytics.'
      operationId: post_analytics_kpi
      parameters:
      - description: The id of the project.
        in: query
        name: project_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KPI'
        description: 'The KPI to post:

          - **component_in_project_id**: the ID of the project component

          - **identifier**: the unique identifier of the KPI

          - **context**: the context of the KPI

          - **type**: the type of the KPI, either "actual" or "potential"

          - **value**: the value of the KPI

          - **units**: the unit of the KPI

          - **units_context** [optional]: the context of the unit. Defaults to "default"

          '
        required: true
        x-body-name: kpi
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: Successful operation. The newly created KPI is returned in the 'resource' field.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request. Details on the error are returned in the 'error' field of the response.
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Post a KPI for a component
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
  /v2/analytics/kpi/{kpi_id}:
    delete:
      description: Delete a KPI of a project with the source user. KPIs with other sources cannot be deleted.
      operationId: delete_user_analytics_kpi
      parameters:
      - description: '[mandatory] The id of the KPI.'
        in: path
        name: kpi_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Bad request.

            The specified KPI cannot be deleted because it was not created by a user.

            '
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Not Found. The specified KPI does not exist.

            '
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Delete a KPI of a project
      tags:
      - Analytics
      x-openapi-router-controller: app.controllers.analytics_controller
  /v2/analytics/kpi_aggregation:
    get:
      description: Returns aggregated KPI results for projects.
      operationId: get_kpi_aggregation
      parameters:
      - description: '[mandatory] The list of project ids.'
        in: query
        name: project_ids
        required: true
        schema:
          items:
            format: int64
            type: integer
          type: array
      - description: '[mandatory] KPI identifier to aggregate.

          Request the **GET /v2/analytics/functions** endpoint to fetch available KPIs.

          '
        in: query
        name: kpi
        required: true
        schema:
          type: string
      - description: The start time of the aggregation interval. It defaults to the current timestamp minus one year.
        in: query
        name: start
        required: false
        schema:
          format: date-time
          type: string
      - description: The end time of the aggregation interval. It defaults to the current timestamp.
        in: query
        name: end
        required: false
        schema:
          format: date-time
          type: string
      - description: 'The length of the time duration for the KPI aggregation.

          **NOTE:** It should be in ISO8601 duration format.

          Examples: P1Y, P5M, P2W, P13D

          '
        in: query
        name: time_window
        required: false
        schema:
          format: iso8601
          type: string
      - description: 'The optional system of units in which the KPI aggregation results should be returned (Example: **metric**).

          Request the **GET /v2/labels/systems** endpoint to fetch available units systems.

          '
        in: query
        name: units_system
        schema:
          type: string
      - description: 'The optional currency system in which the KPI aggregation results should be returned (Example: **EUR**).

          Request the **GET /v2/labels/systems** endpoint to fetch available currency systems.

          '
        in: query
        name: currency_system
        schema:
          type: string
      - description: "Desired aggregation method to be used for aggregating KPI results of a project over the given time interval.\nDefault method: \"mean\"\nAvailable options:\n - \"max\"\n - \"mean\"\n - \"min\"\n - \"sum\"\n"
        in: query
        name: time_aggregation
        required: false
        schema:
          default: mean
          enum:
          - max
          - mean
          - m

# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/aedifion/refs/heads/main/openapi/aedifion-analytics-api-openapi.yml