Aedifion Datapoint 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 Datapoint API
  version: ''
servers:
- url: ''
tags:
- description: Creating, modifying, and accessing datapoints and related resources.
  name: Datapoint
paths:
  /v2/datapoint:
    delete:
      description: 'Deletes a datapoint.

        It requires the virtual datapoints of the datapoint to be stopped and deleted.

        It may take few seconds for the datapoint to be deleted.'
      operationId: delete_datapoint
      parameters:
      - description: The dataPointID of the datapoint to delete.
        in: query
        name: dataPointID
        required: true
        schema:
          type: string
      - description: The numeric id of the project to which the datapoint identified by _dataPointID_ belongs.
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: Successful operation.
        '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 and ''operation'' is set to ''delete''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Forbidden 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 a datapoint
      tags:
      - Datapoint
      x-openapi-router-controller: app.controllers.datapoint_controller
    get:
      description: Gets the data point including meta information, i.e., whether it is a user's favorite, its renamings and tags.
      operationId: get_datapoint
      parameters:
      - description: The dataPointID of the data point to retrieve.
        in: query
        name: dataPointID
        required: true
        schema:
          type: string
      - description: The numeric id of the project to which the data point identified by _dataPointID_ belongs.
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataPointWithContext'
          description: Successful operation. The data point including meta information is returned.
        '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 and ''operation'' is set to ''get''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get details about data point
      tags:
      - Datapoint
      x-openapi-router-controller: app.controllers.datapoint_controller
    put:
      description: Modifies datapoint details such as safety bounds for setpoints.
      operationId: put_datapoint
      parameters:
      - description: The numeric id of the project.
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: The alphanumeric identifier of the datapoint.
        in: query
        name: dataPointID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDatapoint'
        description: 'The details of the update to the data point.

          - **setpoint_min_value** is optional, the minimum allowed value for setpoints

          - **setpoint_max_value** is optional, the maximum allowed value for setpoints

          - **writable** is optional, whether the datapoint can be written to or not

          '
        required: true
        x-body-name: datapoint_details
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The modified datapoint is returned in the ''resource'' field and the ''operation'' is set to ''update''.

            '
        '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 and ''operation'' is set to ''update''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Change datapoint details
      tags:
      - Datapoint
      x-openapi-router-controller: app.controllers.datapoint_controller
  /v2/datapoint/favorite:
    delete:
      description: Removes a data point from the personal favorites of the user.
      operationId: delete_datapoint_favorite
      parameters:
      - description: The dataPointID of the data point to unset as favorite
        in: query
        name: dataPointID
        required: true
        schema:
          type: string
      - description: The numeric id of the project to which the data point identified by _dataPointID_ belongs
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The deleted favorite data point is returned in the ''resource'' field and the ''operation'' is set to ''delete''.

            '
        '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 and ''operation'' is set to ''delete''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Remove a personal favorite data point
      tags:
      - Datapoint
      x-openapi-router-controller: app.controllers.datapoint_controller
    post:
      description: Sets a data point referenced by its name/dataPointID as a favorite for the user.
      operationId: post_datapoint_favorite
      parameters:
      - description: The dataPointID to to mark as favorite
        in: query
        name: dataPointID
        required: true
        schema:
          type: string
      - description: The numeric id of the project to which the data point identified by _dataPointID_ belongs
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The newly created favorite is returned in the ''resource'' field and the ''operation'' is set to ''create''.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unsuccessful operation. Details on the error are returned in the 'error' field.
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Set a data point as personal favorite
      tags:
      - Datapoint
      x-openapi-router-controller: app.controllers.datapoint_controller
  /v2/datapoint/setpoint:
    post:
      description: 'Attempts to write ''value'' with given ''priority'' to the datapoint identified by ''dataPointID'' and ''project_id''.


        This endpoint implements a no-frills, non-acked, stateless, best-effort write service intended for single one-shot setpoint write operations.


        **Please note:**

        - This endpoint returns ''200 - success'' if the setpoint operation is authorized and correctly specified. It does not provide any feedback whether the setpoint has actually been written successfully by the remote building network.'
      operationId: post_datapoint_setpoint
      parameters:
      - description: The dataPointID of the data point for which to write a setpoint.
        in: query
        name: dataPointID
        required: true
        schema:
          type: string
      - description: The numeric id of the project which the data point identified by 'dataPointID' belongs to.
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: The value to write (either a float or 'null' for reset)
        in: query
        name: value
        required: true
        schema:
          type: string
      - in: query
        name: priority
        schema:
          default: 13
          maximum: 16
          minimum: 1
          type: integer
      - description: Request acknowledgement for setpoint write operation.
        in: query
        name: acked
        schema:
          default: false
          type: boolean
      - description: Do a dry run without actually writing anything.
        in: query
        name: dryrun
        schema:
          default: false
          type: boolean
      - description: Ensure the value will not get overwritten by the local BAS.
        in: query
        name: keep_out_of_service
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The setpoint operation has been triggerd but may still fail on the remote side, i.e., the building network.

            If setopint is acked, a reference is returned in the answer that can be used to retrieve status of this operation later.

            '
        '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 ''create''."

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Write a setpoint
      tags:
      - Datapoint
      x-openapi-router-controller: app.controllers.datapoint_controller
  /v2/datapoint/setpoint/{reference}:
    get:
      description: Retrieve the acknowledgement for a setpoint write operation triggered earlier.
      operationId: get_datapoint_setpoint
      parameters:
      - description: The reference of the setpoint write operation.
        in: path
        name: reference
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetpointAck'
          description: 'Successful operation.

            An object containing the details about the setpoint write operation is returned.

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

            '
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Not found.

            Acknowledgement for setpoint write operation could not be found.

            '
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Retrieve acknowledgement for setpoint write operation
      tags:
      - Datapoint
      x-openapi-router-controller: app.controllers.datapoint_controller
  /v2/datapoint/tag:
    post:
      description: Adds a tag to the specified data point.
      operationId: post_datapoint_tag
      parameters:
      - description: The dataPointID of the data point to assign a tag to.
        in: query
        name: dataPointID
        required: true
        schema:
          type: string
      - description: The numeric id of the project to which the data point identified by 'dataPointID' belongs to.
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: The numeric id of the tag which will be assigned to the data point referenced to by 'dataPointID' and 'project_id'.
        in: query
        name: tag_id
        required: true
        schema:
          format: int64
          type: integer
      - description: Flags a tag as correct or incorrect.
        in: query
        name: confirmed
        required: false
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The newly created relation (data point, tag) is returned in the ''resource'' field and the ''operation'' is set to ''create''.

            '
        '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 and ''operation'' is set to ''create''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Add a tag
      tags:
      - Datapoint
      x-openapi-router-controller: app.controllers.datapoint_controller
  /v2/datapoint/tag/{tag_id}:
    delete:
      description: Removes the tag identified by 'id' from the data point identified by 'dataPointID' and 'project_id'.
      operationId: delete_datapoint_tag
      parameters:
      - description: The unique id of the tag to delete.
        in: path
        name: tag_id
        required: true
        schema:
          format: int64
          type: integer
      - description: The dataPointID of the data point from which the tag will be deleted.
        in: query
        name: dataPointID
        required: true
        schema:
          type: string
      - description: The numeric id of the project to which the data point identified by 'dataPointID' belongs to.
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The deleted relation (data point, tag) 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''."

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Remove tag from data point
      tags:
      - Datapoint
      x-openapi-router-controller: app.controllers.datapoint_controller
    put:
      description: Updates the tag identified by 'id' associated with the data point identified by 'dataPointID' and 'project_id'.
      operationId: put_datapoint_tag
      parameters:
      - description: The unique id of the tag to update.
        in: path
        name: tag_id
        required: true
        schema:
          format: int64
          type: integer
      - description: The dataPointID of the associated data point where the tag will be updated.
        in: query
        name: dataPointID
        required: true
        schema:
          type: string
      - description: The numeric id of the project to which the data point identified by 'dataPointID' belongs to.
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTagAssoc'
        description: 'The details of the updated tag.

          - **confirmed** is required, flags a tag as correct or incorrect.

          '
        required: true
        x-body-name: tag
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The updated tag is returned in the ''resource'' field and the ''operation'' is set to ''update''.

            '
        '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 ''update''."

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Update tag associated with data point
      tags:
      - Datapoint
      x-openapi-router-controller: app.controllers.datapoint_controller
  /v2/datapoint/timeseries:
    delete:
      description: Delete timeseries data for a datapoint.
      operationId: delete_datapoint_timeseries
      parameters:
      - description: '**project_id** [mandatory], The id of the project that given datapoint belongs to.'
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: '**dataPointID** [mandatory], the alphanumeric id of the datapoint.'
        in: query
        name: dataPointID
        required: true
        schema:
          type: string
      - description: 'If set to `true` delete all observations.

          If set to `false` delete observations based on given `start` and `end`.

          '
        in: query
        name: all
        schema:
          default: false
          type: boolean
      - description: 'Delete only observations *after* this date-time inclusively.

          **NOTE:** It should be in RFC3999 format.

          If **start** is provided without **end**, all observations *after* **start** are deleted.

          '
        in: query
        name: start
        required: false
        schema:
          format: date-time
          type: string
      - description: 'Delete only observations *before* this date-time inclusively.

          **NOTE:** It should be in RFC3999 format.

          If **end** is provided without **start**, all observations *before* **end** are deleted.

          '
        in: query
        name: end
        required: false
        schema:
          format: date-time
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

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

            Details are returned in the "error" field of the response.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Delete timeseries data for a datapoint
      tags:
      - Datapoint
      x-openapi-router-controller: app.controllers.datapoint_controller
    get:
      description: 'Returns the measured time series data for the specified data point

        referenced by its name/dataPointID for the time interval specified by **start**

        and **end**.

        Returns the last (or respectively next) **max** observations, if either **start** nor **end** are provided.'
      operationId: get_datapoint_timeseries
      parameters:
      - description: The id of the project from which to query observations for a data point
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      - description: Name/ID of the data point, e.g., *bacnet100-4120-CO2*
        in: query
        name: dataPointID
        required: true
        schema:
          type: string
      - description: 'Return only observations *after* this date-time"


          If **start** is provided without **end**, the first **max** elements *after* **start** are returned.

          '
        in: query
        name: start
        required: false
        schema:
          format: date-time
          type: string
      - description: 'Return only observations *before* this date-time".


          If **end** is provided without **start**, the last **max** elements *before* **end** are returned.

          '
        in: query
        name: end
        required: false
        schema:
          format: date-time
          type: string
      - description: 'Maximum number of observations to return.

          - This option is ignored when both **start** and **end** are provided.

          - Setting **max** = 0 returns *all* available data points.

          '
        in: query
        name: max
        required: false
        schema:
          default: 1
          format: int64
          type: integer
      - description: "Desired sampling rate.\nThe returned observations are sampled down to the specified interval. The down sampling will be done by calculating the arithmetic average on all observations made within an interval. The timestamp will represent the beginning of the interval the resampling average is estimated for.\nAllowed intervals are integers combined with durations, like seconds (s), minutes (m), hours (h), and days (d), e.g.\n - \"10s\" specifies a sampling rate of \"once every 10 seconds\",\n - \"1h\" specifies a sampling rate of \"once every (1) hour\",\n - \"0s\", \"0m\", \"0h\", ... specify highest sampling rate available\n - \"auto\" specifies an automatic sampling rate\n"
        in: query
        name: samplerate
        schema:
          type: string
      - description: "Desired interpolation method.\nThis option is to be used while resampling. While resampling, the specified method will be used to interpolate missing data.\nDefault method: \"previous\"\nAvailable options:\n - \"previous\" Reports the value from the previous time interval for time intervals with no data.\n - \"linear\" Reports the results of linear interpolation for time intervals with no data.\n - \"null\" Reports null for time intervals with no data but returns a timestamp. This is the same as the default behavior.\n - \"none\"  Reports no timestamp and no value for time intervals with no data.\n"
        in: query
        name: interpolation
        schema:
          default: previous
          enum:
          - previous
          - linear
          - 'null'
          - none
          type: string
      - description: "Desired aggregation method to be used while interpolating over a timeframe.\nDefault method: \"mean\"\nAvailable options:\n - \"mean\"\n - \"min\"\n - \"max\"\n - \"mode\"\n - \"median\"\n - \"distinct\"\n - \"count\"\n"
        in: query
        name: aggregation
        required: false
        schema:
          default: mean
          enum:
          - mean
          - min
          - max
          - mode
          - median
          - distinct
          - count
          type: string
      - description: "Return only list of timeseries data format, i.e.\n - without tags\n - compressed timeseries format, i.e. [(time1, val1), ..., (timen, valn)]\n"
        in: query
        name: short
        schema:
          default: false
          type: boolean
      - description: 'Returns the last recorded value on the requested start and end timestamp if there does not exist an observation at this precise time.

          '
        in: query
        name: closed_interval
        schema:
          default: false
          type: boolean
      - description: 'The optional system of units in which the timeseries data 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 timeseries data 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: 'The optional units in which the timeseries data should be returned.

          This overrides the **units_system** and **currency_system** parameters.

          '
        in: query
        name: units
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeseriesWithContext'
          description: Successful operation. A list of observations for the specified data point is returned.
        '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 and ''operation'' is set to ''get''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'At least one datapoint could not be converted, e.g., due to the missing `units` tag or the requested unit conversion is not supported.

            '
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get the time series data of a data point
      tags:
      - Datapoint
      x-openapi-router-controller: app.controllers.datapoint_controller
components:
  schemas:
    Timeseries:
      items:
        $ref: '#/components/schemas/Observation'
      type: array
    UpdateTagAssoc:
      properties:
        confirmed:
          enum:
          - 'true'
          - 'false'
          - unconfirmed
          type: string
      type: object
    Tag:
      properties:
        id:
          format: int64
          type: integer
        key:
          type: string
        value:
          type: string
      required:
      - id
      - key
      type: object
    Renaming:
      properties:
        datapointkey_id:
          format: int64
          type: integer
        id:
          format: int64
          type: integer
        renaming:
          type: string
      type: object
    DataPointWithContext:
      properties:
        dataPointID:
          type: string
        favorite:
          type: boolean
        hash_id:
          type: string
        id:
          type: integer
        renamings:
          items:
            $ref: '#/components/schemas/Renaming'
          type: array
        setpoint_max_value:
          type: number
        setpoint_min_value:
          type: number
        tags:
          items:
            $ref: '#/components/schemas/TagAssociation'
          type: array
        writable:
          type: boolean
      type: object
    Observation:
      properties:
        time:
          type: string
        value:
          format: float
          type: number
      required:
      - time
      - value
    Error:
      properties:
        details:
          properties: {}
          type: object
        error:
          type: string
        operation:
          enum:
          - ''
          - get
          - create
          - delete
          - update
          type: string
        success:
          default: false
          type: boolean
      required:
      - error
      type: object
    UpdateDatapoint:
      properties:
        setpoint_max_value:
          type: number
        setpoint_min_value:
          type: number
        writable:
          type: boolean
      type: object
    TimeseriesWithContext:
      properties:
        data:
          $ref: '#/components/schemas/Timeseries'
        dataPointID:
          type: string
        datapoint_hash_id:
          type: string
        error:
          description: 'Optional error message describing why the data could not be loaded or processed, for example due to a unit conversion failure or missing units tag.

            '
          type: string
        tags:
          items:
            $ref: '#/components/schemas/TagAssociation'
          type: array
        units:
          type: string
    TagAssociation:
      allOf:
      - $ref: '#/components/schemas/Tag'
      - properties:
          confirmed:
            type: boolean
          probability:
            type: number
          protected:
            type: boolean
          source:
            type: string
        type: object
    Success:
      properties:
        message:
          type: string
        operation:
          enum:
          - ''
          - get
          - create
          - delete
          - update
          type: string
        resource:
          properties: {}
          type: object
        success:
          default: true
          type: boolean
      type: object
    SetpointAck:
      properties:
        dataPointID:
          type: string
        log:
          type: string
        priority:
          type: integer
        project_id:
          format: int64
          type: integer
        reference:
          type: string
        state_before:
          type: object
        status:
          type: string
        value:
          type: string
      type: object
  securitySchemes:
    basicAuth:
      scheme: basic
      type: http
      x-basicInfoFunc: app.controllers.auth.connexion_basic_auth
    openIDConnect:
      flows:
        implicit:
          authorizationUrl: https://auth.aedifion.io/realms/aedifion/protocol/openid-connect/auth
          scopes:
            openid: Use OpenID Connect (required)
      type: oauth2
      x-tokenInfoFunc: app.controllers.auth.connexion_token_info