Verdigris Technologies Energy API

openapi: 3.1.0
info:
  title: Data Control Energy API
  description: Microservice that serves insightful power and energy data
  version: '1.1'
  contact:
    name: Verdigris Support
    email: support@verdigris.co
    url: https://docs.verdigris.co/
  termsOfService: https://verdigris.co/terms
servers:
- url: https://api.verdigris.co/data/v4
security:
- oauth2: []
tags:
- name: Energy
  description: Endpoints that return energy data
paths:
  /energy/breakers:
    get:
      tags:
      - Energy
      operationId: getBatchBreakerEnergy
      summary: Batch breaker energy
      description: 'Gets energy data for multiple breakers in a single batch request. Units are in watt-hour (SI unit: **Wh**) if `type` query parameter is `real`, volt-ampere-hour (SI unit: **VAh**) if `type` query parameter is `apparent`.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/breakerIds'
      - $ref: '#/components/parameters/interval'
      - $ref: '#/components/parameters/intervalScopedStartTime'
      - $ref: '#/components/parameters/intervalScopedEndTime'
      - $ref: '#/components/parameters/timestampFormat'
      - $ref: '#/components/parameters/timezone'
      - $ref: '#/components/parameters/energyType'
      responses:
        '200':
          $ref: '#/components/responses/successEnergy'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /energy/buildings:
    get:
      tags:
      - Energy
      operationId: getBatchBuildingEnergy
      summary: Batch building energy
      description: 'Gets energy data for multiple buildings in a single batch request. Units are in watt-hour (SI unit: **Wh**) if `type` query parameter is `real`, volt-ampere-hour (SI unit: **VAh**) if `type` query parameter is `apparent`.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/buildingIds'
      - $ref: '#/components/parameters/interval'
      - $ref: '#/components/parameters/intervalScopedStartTime'
      - $ref: '#/components/parameters/intervalScopedEndTime'
      - $ref: '#/components/parameters/timestampFormat'
      - $ref: '#/components/parameters/timezone'
      - $ref: '#/components/parameters/energyType'
      responses:
        '200':
          $ref: '#/components/responses/successEnergy'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /energy/circuits:
    get:
      tags:
      - Energy
      operationId: getBatchCircuitEnergy
      summary: Batch circuit energy
      description: 'Gets energy data for multiple circuits in a single batch request. Units are in watt-hour (SI unit: **Wh**) if `type` query parameter is `real`, volt-ampere-hour (SI unit: **VAh**) if `type` query parameter is `apparent`.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/circuitIds'
      - $ref: '#/components/parameters/interval'
      - $ref: '#/components/parameters/intervalScopedStartTime'
      - $ref: '#/components/parameters/intervalScopedEndTime'
      - $ref: '#/components/parameters/timestampFormat'
      - $ref: '#/components/parameters/timezone'
      - $ref: '#/components/parameters/energyType'
      - $ref: '#/components/parameters/phaseCxOverride'
      - $ref: '#/components/parameters/reverseCxOverride'
      responses:
        '200':
          $ref: '#/components/responses/successEnergy'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /energy/panels:
    get:
      tags:
      - Energy
      operationId: getBatchPanelEnergy
      summary: Batch panel energy
      description: 'Gets energy data for multiple panels in a single batch request. Units are in watt-hour (SI unit: **Wh**) if `type` query parameter is `real`, volt-ampere-hour (SI unit: **VAh**) if `type` query parameter is `apparent`.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/panelIds'
      - $ref: '#/components/parameters/interval'
      - $ref: '#/components/parameters/intervalScopedStartTime'
      - $ref: '#/components/parameters/intervalScopedEndTime'
      - $ref: '#/components/parameters/timestampFormat'
      - $ref: '#/components/parameters/timezone'
      - $ref: '#/components/parameters/energyType'
      responses:
        '200':
          $ref: '#/components/responses/successEnergy'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /energy/breakers/{id}:
    get:
      tags:
      - Energy
      operationId: getBreakerEnergy
      summary: Breaker energy
      description: 'Gets energy data for a breaker. Units are in watt-hour (SI unit: **Wh**) if `type` query parameter is `real`, volt-ampere-hour (SI unit: **VAh**) if `type` query parameter is `apparent`.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/breakerId'
      - $ref: '#/components/parameters/interval'
      - $ref: '#/components/parameters/intervalScopedStartTime'
      - $ref: '#/components/parameters/intervalScopedEndTime'
      - $ref: '#/components/parameters/timestampFormat'
      - $ref: '#/components/parameters/timezone'
      - $ref: '#/components/parameters/energyType'
      responses:
        '200':
          $ref: '#/components/responses/successEnergy'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /energy/buildings/{id}:
    get:
      tags:
      - Energy
      operationId: getBuildingEnergy
      summary: Building energy
      description: 'Gets energy data for a building. Units are in watt-hour (SI unit: **Wh**) if `type` query parameter is `real`, volt-ampere-hour (SI unit: **VAh**) if `type` query parameter is `apparent`.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/buildingId'
      - $ref: '#/components/parameters/interval'
      - $ref: '#/components/parameters/intervalScopedStartTime'
      - $ref: '#/components/parameters/intervalScopedEndTime'
      - $ref: '#/components/parameters/timestampFormat'
      - $ref: '#/components/parameters/timezone'
      - $ref: '#/components/parameters/energyType'
      responses:
        '200':
          $ref: '#/components/responses/successEnergy'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /energy/circuits/{id}:
    get:
      tags:
      - Energy
      operationId: getCircuitEnergy
      summary: Circuit energy
      description: 'Gets energy data for a circuit. Units are in watt-hour (SI unit: **Wh**) if `type` query parameter is `real`, volt-ampere-hour (SI unit: **VAh**) if `type` query parameter is `apparent`.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/circuitId'
      - $ref: '#/components/parameters/interval'
      - $ref: '#/components/parameters/intervalScopedStartTime'
      - $ref: '#/components/parameters/intervalScopedEndTime'
      - $ref: '#/components/parameters/timestampFormat'
      - $ref: '#/components/parameters/timezone'
      - $ref: '#/components/parameters/energyType'
      - $ref: '#/components/parameters/phaseCxOverride'
      - $ref: '#/components/parameters/reverseCxOverride'
      responses:
        '200':
          $ref: '#/components/responses/successEnergy'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /energy/panels/{id}:
    get:
      tags:
      - Energy
      operationId: getPanelEnergy
      summary: Panel energy
      description: 'Gets energy data for a panel. Units are in watt-hour (SI unit: **Wh**) if `type` query parameter is `real`, volt-ampere-hour (SI unit: **VAh**) if `type` query parameter is `apparent`.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/panelId'
      - $ref: '#/components/parameters/interval'
      - $ref: '#/components/parameters/intervalScopedStartTime'
      - $ref: '#/components/parameters/intervalScopedEndTime'
      - $ref: '#/components/parameters/timestampFormat'
      - $ref: '#/components/parameters/timezone'
      - $ref: '#/components/parameters/energyType'
      responses:
        '200':
          $ref: '#/components/responses/successEnergy'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
components:
  schemas:
    successEnergyJSONEpoch:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
            example: 12345
          timestamp:
            type: integer
            example: 1546301700000
          energy:
            type: number
            format: float
            example: 18273.97233876
    successEnergyCSVEpoch:
      type: string
      example: 'id,timestamp,energy

        12345,1546301700000,18273.97233876

        '
    permissionsInvalidError:
      type: object
      properties:
        name:
          type: string
          example: UnauthorizedError
        message:
          type: string
          example: Permissions should be an Array or String. Bad format?
        code:
          type: string
          example: permissions_invalid
        status:
          type: integer
          example: 403
    successEnergyJSONISO8601:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
            example: 12345
          timestamp:
            type: string
            format: date-time
            example: '2020-01-01T00:15:00Z'
          energy:
            type: number
            format: float
            example: 18273.97233876
    permissionDeniedError:
      type: object
      properties:
        name:
          type: string
          example: UnauthorizedError
        message:
          type: string
          example: Permission denied
        code:
          type: string
          example: permission_denied
        status:
          type: integer
          example: 403
    entityNotFoundError:
      type: object
      properties:
        name:
          type: string
          example: EntityNotFoundError
        message:
          type: string
          example: One or more entity with given IDs does not exist in your account.
        status:
          type: integer
          example: 404
        invalidIds:
          type: array
          items:
            type: integer
          example:
          - 1
          - 2
          - 3
    unauthorizedError:
      type: object
      properties:
        name:
          type: string
          example: UnauthorizedError
        message:
          type: string
          example: No authorization token was found
        code:
          type: string
          example: credentials_required
        status:
          type: integer
          example: 401
    unprocessableEntityError:
      type: object
      properties:
        name:
          type: string
          example: UnprocessableEntityError
        message:
          type: string
          example: Validation error
        status:
          type: integer
          example: 422
        errors:
          type: array
          items:
            $ref: '#/components/schemas/validationError'
    successEnergyCSVISO8601:
      type: string
      example: 'id,timestamp,energy

        12345,2020-01-01T00:15:00Z,18273.97233876

        '
    validationError:
      type: object
      properties:
        location:
          type: string
          example: query
        msg:
          type: string
          example: must be in ISO 8601 format
        param:
          type: string
          example: start_time
        value:
          type: string
          example: 1:15PM 10/13/1999
  responses:
    successEnergy:
      description: Energy data for given time range. The ordering of timestamps is not guaranteed.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/successEnergyJSONEpoch'
            - $ref: '#/components/schemas/successEnergyJSONISO8601'
        text/csv:
          schema:
            oneOf:
            - $ref: '#/components/schemas/successEnergyCSVEpoch'
            - $ref: '#/components/schemas/successEnergyCSVISO8601'
    unprocessableEntity:
      description: One or more validations for request has failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/unprocessableEntityError'
    forbidden:
      description: Request to resource is forbidden due to insufficient permissions.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/permissionDeniedError'
            - $ref: '#/components/schemas/permissionsInvalidError'
    entityNotFound:
      description: Resource with given ID cannot be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/entityNotFoundError'
    unauthorized:
      description: 'Request to resource is unauthorized. This is likely due to missing access token in the `Authorization` header or an invalid token signature usually as a result of attempted token forgery by an unauthorized third-party.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/unauthorizedError'
  parameters:
    buildingIds:
      in: query
      name: ids
      description: An array of building IDs separated by commas.
      required: true
      style: form
      explode: false
      schema:
        type: array
        items:
          type: integer
        minItems: 1
    interval:
      in: query
      name: interval
      description: 'Interval between each data points. Affects the validity of `start_time`, `end_time` query parameters, time resolution and aggregation of results.


        For example, given the time range query parameters, `start_time=2020-01-01T12:30:00Z&end_time=2020-01-01T13:00:00Z`:


        - `interval=1m`: returns 30 data points at minutely resolution.

        - `interval=15m`: returns 2 data points at 15-minutesly/quarter-hourly resolution.


        The ordering of timestamps is not guaranteed.

        '
      required: true
      schema:
        type: string
        enum:
        - 1m
        - 15m
        - 1h
        - 1d
        - 1M
    accept:
      in: header
      name: Accept
      description: 'Specify a [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml) to indicate the content type the client would like to receive the data in. If omitted, defaults to `application/json`.


        Currently, the supported formats are:


        - `application/json`

        - `text/csv`

        '
      required: false
      schema:
        type: string
        default: application/json
        enum:
        - application/json
        - text/csv
    intervalScopedStartTime:
      name: start_time
      in: query
      description: "Start of the query time range. Value must be in [ISO 8601](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14) format.\n\nNote that validity of `start_time` changes depending on the `interval` query parameter.\n\nFor example:\n\n- **VALID**: `start_time=2020-01-01T12:34:00Z&interval=1m`\n- **VALID**: `start_time=2020-01-01T12:45:00Z&interval=15m`\n- **VALID**: `start_time=2020-01-01T13:00:00Z&interval=1h`\n- **VALID** (if building’s timezone is in Pacific Standard Time):\n  - `start_time=2020-01-01T08:00:00Z&interval=1d` (UTC)\n  - `start_time=2020-01-01T00:00:00+08:00&interval=1d` (PST)\n- **NOT VALID**: `start_time=2020-01-01T12:34:00Z&interval=15m`\n- **NOT VALID**: `start_time=2020-01-01T12:59:00Z&interval=1h`\n- **NOT VALID** (if building’s timezone is in Pacific Standard Time):\n  - `start_time=2020-01-01T00:00:00Z&interval=1d`\n  - `start_time=2020-01-01T04:00:00+08:00&interval=1d`\n"
      required: true
      schema:
        type: string
        format: date-time
    phaseCxOverride:
      in: query
      name: override_phase
      description: '> ⚠️ Warning

        >

        > This query parameter is intended for advanced users troubleshooting potentially incorrect data. Incorrect use of this query parameter can lead to erroneous data.


        Overrides the configured phase for this circuit and returns the data as if the circuit was on the specified phase.


        When omitted, the circuit will reference the phase based on the current panel configuration.

        '
      required: false
      schema:
        type: string
        enum:
        - A
        - B
        - C
    energyType:
      name: type
      in: query
      description: 'Type of energy:


        - `real`: Energy calculated from real (true) power over given time interval. Returns energy in watt-hour (SI unit: **Wh**).

        - `apparent`: Energy calculated from apparent power over given time interval. Returns energy in volt-ampere-hour (SI unit: **VAh**). Apparent energy is not supported for daily interval.

        '
      required: false
      schema:
        type: string
        default: real
        nullable: true
        enum:
        - real
        - apparent
    intervalScopedEndTime:
      name: end_time
      in: query
      description: "End of the query time range. Value must be in [ISO 8601](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14) format.\n\nNote that validity of `end_time` changes depending on the `interval` query parameter.\n\nFor example:\n\n- **VALID**: `end_time=2020-12-31T12:34:00Z&interval=1m`\n- **VALID**: `end_time=2020-12-31T12:45:00Z&interval=15m`\n- **VALID**: `end_time=2020-12-31T13:00:00Z&interval=1h`\n- **VALID** (if building’s timezone is in Pacific Standard Time):\n  - `end_time=2020-12-31T08:00:00Z&interval=1d` (UTC)\n  - `end_time=2020-12-31T00:00:00+08:00&interval=1d` (PST)\n- **NOT VALID**: `end_time=2020-12-31T12:34:00Z&interval=15m`\n- **NOT VALID**: `end_time=2020-12-31T12:59:00Z&interval=1h`\n- **NOT VALID** (if building’s timezone is in Pacific Standard Time):\n  - `end_time=2020-12-31T00:00:00Z&interval=1d`\n  - `end_time=2020-12-31T04:00:00+08:00&interval=1d`\n"
      required: true
      schema:
        type: string
        format: date-time
    panelId:
      in: path
      name: id
      description: Panel ID
      required: true
      schema:
        type: integer
    breakerId:
      in: path
      name: id
      description: Breaker ID
      required: true
      schema:
        type: integer
    buildingId:
      in: path
      name: id
      description: Building ID
      required: true
      schema:
        type: integer
    timestampFormat:
      name: timestamp_format
      in: query
      description: 'Format timestamps in the data. If set to `ISO8601` (case-insensitive), the timestamp is returned as a string formatted in [ISO 8601](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14) format. If omitted, the timestamp is returned as an integer representing [UNIX epoch](https://en.wikipedia.org/wiki/Unix_time).

        '
      required: false
      schema:
        type: string
        nullable: true
        enum:
        - ISO8601
    reverseCxOverride:
      in: query
      name: override_sensor_orientation
      description: '> ⚠️ Warning

        >

        > This query parameter is intended for advanced users troubleshooting potentially incorrect data. Incorrect use of this query parameter can lead to erroneous data.


        Overrides the configured sensor orientation to return circuit data as if the CT was clamped upside down and flip positive values to negative and vice versa.


        When omitted, the API will compute the data by referencing the sensor orientation based on the current panel configuration.

        '
      required: false
      schema:
        type: string
        enum:
        - normal
        - reversed
    breakerIds:
      in: query
      name: ids
      description: An array of breaker IDs separated by commas.
      required: true
      style: form
      explode: false
      schema:
        type: array
        items:
          type: integer
        minItems: 1
    panelIds:
      in: query
      name: ids
      description: An array of panel IDs separated by commas.
      required: true
      style: form
      explode: false
      schema:
        type: array
        items:
          type: integer
        minItems: 1
    circuitId:
      in: path
      name: id
      description: Circuit ID
      required: true
      schema:
        type: integer
    timezone:
      name: timezone
      in: query
      description: "When used in conjunction with `timestamp_format` query parameter that is set to `ISO8601` format, specifying the [zone ID](https://nodatime.org/TimeZones) of [IANA Time Zone Database](https://www.iana.org/time-zones) returns the timestamp in the time zone offset.\n\nSetting the timezone when `timestamp_format` is not specified has no affect on the UNIX epoch timestamp.\n\n> \uD83D\uDCD8 Note\n>\n> This query parameter meant to be a convenience feature that only affects the _display format_ of the timestamps in the result. It has no affect on the building’s timezone.\n"
      required: false
      schema:
        type: string
        default: UTC
        format: zoneid
      examples:
        America/New_york:
          summary: US/Eastern
          value: America/New_york
        America/Chicago:
          summary: US/Central
          value: America/Chicago
        America/Denver:
          summary: US/Mountain
          value: America/Denver
        America/Los_angeles:
          summary: US/Pacific
          value: America/Los_angeles
        America/Anchorage:
          summary: US/Alaska
          value: America/Anchorage
        Pacific/Honolulu:
          summary: US/Hawaii
          value: Pacific/Honolulu
    circuitIds:
      in: query
      name: ids
      description: An array of circuit IDs separated by commas.
      required: true
      style: form
      explode: false
      schema:
        type: array
        items:
          type: integer
        minItems: 1
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.verdigris.co/oauth/token
          scopes: {}