Verdigris Technologies Power API

openapi: 3.2.0
info:
  title: Data Power 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: Power
  description: Endpoints that return power data
paths:
  /power/breakers:
    get:
      tags:
      - Power
      operationId: getBatchBreakerPower
      summary: Batch breaker power
      description: 'Gets average power data for multiple breakers in a single batch request. Units are in watts (SI unit: **W**).'
      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'
      responses:
        '200':
          $ref: '#/components/responses/successPower'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /power/buildings:
    get:
      tags:
      - Power
      operationId: getBatchBuildingPower
      summary: Batch building power
      description: 'Gets average power data for multiple buildings in a single batch request. Units are in watts (SI unit: **W**).'
      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'
      responses:
        '200':
          $ref: '#/components/responses/successPower'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /power/circuits:
    get:
      tags:
      - Power
      operationId: getBatchCircuitPower
      summary: Batch circuit power
      description: 'Gets average power data for multiple circuits in a single batch request. Units are in watts (SI unit: **W**).'
      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/phaseCxOverride'
      - $ref: '#/components/parameters/reverseCxOverride'
      responses:
        '200':
          $ref: '#/components/responses/successPower'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /power/panels:
    get:
      tags:
      - Power
      operationId: getBatchPanelPower
      summary: Batch panel power
      description: 'Gets average power data for multiple panels in a single batch request. Units are in watts (SI unit: **W**).'
      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'
      responses:
        '200':
          $ref: '#/components/responses/successPower'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /power/breakers/{id}:
    get:
      tags:
      - Power
      operationId: getBreakerPower
      summary: Breaker power
      description: 'Gets average power data for a breaker. Units are in watts (SI unit: **W**).'
      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'
      responses:
        '200':
          $ref: '#/components/responses/successPower'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /power/buildings/{id}:
    get:
      tags:
      - Power
      operationId: getBuildingPower
      summary: Building power
      description: 'Gets average power data for a building. Units are in watts (SI unit: **W**).'
      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'
      responses:
        '200':
          $ref: '#/components/responses/successPower'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /power/circuits/{id}:
    get:
      tags:
      - Power
      operationId: getCircuitPower
      summary: Circuit power
      description: 'Gets average power data for a circuit. Units are in watts (SI unit: **W**) for real power, volt-amperes (SI unit: **VA**) for apparent power, and volt-amperes-reactive (SI unit: **VAr**) for reactive power.'
      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/phaseCxOverride'
      - $ref: '#/components/parameters/reverseCxOverride'
      responses:
        '200':
          $ref: '#/components/responses/successPower'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /power/panels/{id}:
    get:
      tags:
      - Power
      operationId: getPanelPower
      summary: Panel power
      description: 'Gets average power data for a panel. Units are in watts (SI unit: **W**).'
      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'
      responses:
        '200':
          $ref: '#/components/responses/successPower'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
components:
  parameters:
    breakerId:
      in: path
      name: id
      description: Breaker 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
    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
    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
    circuitId:
      in: path
      name: id
      description: Circuit ID
      required: true
      schema:
        type: integer
    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
    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
    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
    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.


        Setting the timezone when `timestamp_format` is not specified has no affect on the UNIX epoch timestamp.


        > 📘 Note

        >

        > 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.

        '
      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
    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
    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
    buildingId:
      in: path
      name: id
      description: Building ID
      required: true
      schema:
        type: integer
    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
    panelId:
      in: path
      name: id
      description: Panel ID
      required: true
      schema:
        type: integer
    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
  schemas:
    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
    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
    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
    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
    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
    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'
    successPowerCSVEpoch:
      type: string
      example: 'id,timestamp,power

        12345,1546301700000,18273.97233876

        '
    successPowerJSONISO8601:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
            example: 12345
          timestamp:
            type: string
            format: date-time
            example: '2020-01-01T00:15:00Z'
          power:
            type: number
            format: float
            example: 18273.97233876
    successPowerCSVISO8601:
      type: string
      example: 'id,timestamp,power

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

        '
    successPowerJSONEpoch:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
            example: 12345
          timestamp:
            type: integer
            example: 1546301700000
          power:
            type: number
            format: float
            example: 18273.97233876
  responses:
    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'
    entityNotFound:
      description: Resource with given ID cannot be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/entityNotFoundError'
    successPower:
      description: Power data for given time range. The ordering of timestamps is not guaranteed.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/successPowerJSONEpoch'
            - $ref: '#/components/schemas/successPowerJSONISO8601'
        text/csv:
          schema:
            oneOf:
            - $ref: '#/components/schemas/successPowerCSVEpoch'
            - $ref: '#/components/schemas/successPowerCSVISO8601'
    forbidden:
      description: Request to resource is forbidden due to insufficient permissions.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/permissionDeniedError'
            - $ref: '#/components/schemas/permissionsInvalidError'
    unprocessableEntity:
      description: One or more validations for request has failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/unprocessableEntityError'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.verdigris.co/oauth/token
          scopes: {}