Enode Meters API

openapi: 3.2.0
info:
  title: Enode Meters API
  version: '2023-08-01'
  description: One integration, 1000+ energy devices.
  license:
    name: Enode Commercial License
    url: https://enode.com
servers:
- url: https://enode-api.production.enode.io
tags:
- name: Meters
  description: The `Meter` object represents a unit responsible for measuring energy usage. It provides detailed information about the meter itself and the energy consumption data it records.
paths:
  /meters/{meterId}:
    get:
      summary: Get Meter
      operationId: getMeter
      tags:
      - Meters
      security:
      - ClientAccessToken: []
      parameters:
      - $ref: '#/components/parameters/PathMeterId'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Meter'
  /meters/{meterId}/refresh-hint:
    post:
      summary: Refresh meter data
      description: 'Use this endpoint to initiate an expedited data refresh for the specified meter.


        Note: The Enode platform keeps data automatically up-to-date and detects changes in the OEM APIs within seconds to a few minutes. We change the refresh interval dynamically based on a number of heuristics. This ensures we find the best trade-off between the stability of the connection to the OEM and freshness of the data.

        This method overrides most of our heuristics and should therefore be used with caution. You may use it when you have a strong reason to believe the data might be stale.'
      operationId: metersRefreshHint
      tags:
      - Meters
      security:
      - ClientAccessToken: []
      parameters:
      - $ref: '#/components/parameters/PathMeterId'
      responses:
        '204':
          description: Refresh hint registered successfully.
          content: {}
        '404':
          description: The specified meter was not found.
        '429':
          description: Rate limited. Retry after the number of seconds given in the Retry-After header.
          headers:
            Retry-After:
              schema:
                type: string
                pattern: ^\d+$
                description: Seconds until the current UTC hour resets and another refresh hint can be submitted.
                example: '1800'
              required: true
              description: Seconds until the current UTC hour resets and another refresh hint can be submitted.
          content:
            application/problem+json:
              example:
                type: https://docs.enode.io/api/problems/rate-limited
                title: Rate limited
                detail: You have reached the maximum number of 9 refresh-hints per hour for this device.
              schema:
                $ref: '#/components/schemas/Problem'
  /users/{userId}/meters:
    get:
      summary: List User Meters
      description: Returns a paginated list of meters for the given userId.
      operationId: listUserMeters
      tags:
      - Meters
      security:
      - ClientAccessToken: []
      parameters:
      - $ref: '#/components/parameters/UserPathId'
      - $ref: '#/components/parameters/PaginationQueryAfter'
      - $ref: '#/components/parameters/PaginationQueryBefore'
      - $ref: '#/components/parameters/PaginationQueryPageSize'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedMeterList'
  /meters:
    get:
      summary: List Meters
      operationId: listMeters
      description: Returns a paginated list of all Meters.
      tags:
      - Meters
      security:
      - ClientAccessToken: []
      parameters:
      - $ref: '#/components/parameters/PaginationQueryAfter'
      - $ref: '#/components/parameters/PaginationQueryBefore'
      - $ref: '#/components/parameters/PaginationQueryPageSize'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedMeterList'
components:
  schemas:
    PaginatedMeterList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Meter'
          description: Paginated list of meters
        pagination:
          $ref: '#/components/schemas/PaginationCursors'
      required:
      - data
      - pagination
      additionalProperties: false
      description: Paginated response of meters
    Brand:
      type: string
      description: A formatted and properly cased OEM brand name, suitable for reading by humans. May contain special characters.
      example: Tesla
    Capability:
      type: object
      properties:
        isCapable:
          type: boolean
          description: The entity is fully capable of providing this data or functionality. If false, support is partial or missing. A capable entity (`true`) may still list recommended interventions in `interventionIds`.
          example: false
        interventionIds:
          type: array
          items:
            type: string
            example: 4eaeb363-296d-4ccc-a973-7805e6f400bd
            x-format:
              guid: true
          description: 'IDs of interventions the user can make to alter the availability of this capability.

            Interventions may be present even when `isCapable` is `true` (recommended, non-blocking actions). See [the interventions guide](/docs/interventions#accessing-interventions-via-our-api).'
      required:
      - isCapable
      - interventionIds
      additionalProperties: false
    PaginationQueryAfter:
      type: string
      description: Opaque cursor used to fetch next page. Cannot be set together with `before`. Refer to [Pagination](/api#pagination) for more information.
      example: MjAyMy0wNy0xOFQxMDowODowMi4zNzNa
    PaginationQueryBefore:
      type: string
      description: Opaque cursor used to fetch previous page. Cannot be used together with `after`. Refer to [Pagination](/api#pagination) for more information.
      example: MjAyMy0wNy0xOFQxMDowODowMi4zNzNa
    Meter:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the meter object
        userId:
          type: string
          description: The ID of the user that linked this meter.
          example: bb28471e-cde6-4eff-ace4-9a7f4f50882a
        vendor:
          $ref: '#/components/schemas/MeterVendor'
        lastSeen:
          type: string
          format: date-time
          description: The last time Enode successfully communicated with the vendor or when the meter was initially linked.
          example: '2020-04-07T17:04:26Z'
        isReachable:
          type: boolean
          description: Indicates whether Enode can currently access live data from the meter. If the meter is not reachable, data updates will be delayed.
        information:
          $ref: '#/components/schemas/MeterInformation'
        energyState:
          $ref: '#/components/schemas/MeterEnergyState'
        location:
          $ref: '#/components/schemas/MeterLocation'
        capabilities:
          $ref: '#/components/schemas/MeterCapabilities'
        scopes:
          type: array
          items:
            type: string
          description: Scopes that the user has granted for this meter.
          example:
          - meter:read:data
          - meter:read:location
      required:
      - id
      - userId
      - vendor
      - lastSeen
      - isReachable
      - information
      - energyState
      - location
      - capabilities
      - scopes
      additionalProperties: false
    MeterCapabilities:
      type: object
      properties:
        measuresConsumption:
          allOf:
          - $ref: '#/components/schemas/Capability'
          description: Indicates if the meter can measure consumed energy.
        measuresProduction:
          allOf:
          - $ref: '#/components/schemas/Capability'
          description: Indicates if the meter can measure energy produced or generated.
      required:
      - measuresConsumption
      - measuresProduction
      additionalProperties: false
      description: The specific meter's capabilities for recording energy consumption and production data.
    UserPathId:
      type: string
      description: ID of the User.
    MeterEnergyState:
      type: object
      properties:
        power:
          type:
          - number
          - 'null'
          description: "The current power measured by the meter in kW. \n\n * Positive value: Power is imported from the grid to the site, indicating consumption. \n * Negative value: Power is exported to the grid, typically when the site generates excess electricity (e.g. from solar panels, or battery discharge). "
          example: 2.2
        lastUpdated:
          type:
          - string
          - 'null'
          format: date-time
          description: Time of last received energy state update.
          example: '2022-03-01T12:34:56Z'
      required:
      - power
      - lastUpdated
      additionalProperties: false
      description: Latest information about meter load. `null` values indicate we are unable to determine a value for the field based on the information coming from the vendor.
    PaginationQueryPageSize:
      type: integer
      description: Number of records to return per page. Default page size is 50.
      example: 50
      exclusiveMinimum: 0
    Problem:
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type.
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        issues:
          type: array
          items:
            type: object
            properties: {}
          description: A list of validation issues which occurred while validating some component of the network payload.
      required:
      - type
      - title
      - detail
      description: Standard Problem Error
      example:
        type: https://docs.enode.io/api/problems/not-found
        title: Not Found
        detail: The requested asset wasn't found.
    MeterLocation:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          example: 8d90101b-3f2f-462a-bbb4-1ed320d33bbe
          x-format:
            guid: true
          description: ID of the location the meter is currently positioned at (if any).
        longitude:
          type:
          - number
          - 'null'
          description: Longitude in degrees
          example: 10.7197486
        latitude:
          type:
          - number
          - 'null'
          description: Latitude in degrees
          example: 59.9173985
        lastUpdated:
          type:
          - string
          - 'null'
          format: date-time
          description: Time of last received location state update
          example: '2024-01-07T17:04:26.000Z'
      required:
      - id
      - longitude
      - latitude
      - lastUpdated
      additionalProperties: false
      description: Meter's GPS coordinates
    PathMeterId:
      type: string
      description: The ID of the meter you are looking up
      example: 54d827e1-8355-4fed-97b5-55940d1d09ba
    MeterVendor:
      type: string
      enum:
      - ENPHASE
      - GIVENERGY
      - FOXESS
      - HUAWEI
      - SMA
      - SOLAREDGE
      - SOLIS
      - SOLAX
      - SUNGROW
      - TESLA
      - GROWATT
      description: Machine-friendly name of the vendor. Use this in API requests.
      example: TESLA
    MeterInformation:
      type: object
      properties:
        brand:
          $ref: '#/components/schemas/Brand'
        model:
          type: string
          description: Meter model
          example: Tesla Powerwall built-in meter
        siteName:
          type: string
          description: Name of the site, as set by the user on the device/vendor. If no user-specified name is available, we construct a fallback name using the vendor/device/model names.
          example: Powerwall Home
        installationDate:
          type: string
          format: date-time
          description: Meter installation date
          example: '2020-04-07T17:04:26Z'
      required:
      - brand
      - model
      - siteName
      - installationDate
      additionalProperties: false
      description: Descriptive information about the meter
    PaginationCursors:
      type: object
      properties:
        after:
          type:
          - string
          - 'null'
          example: MjAyMy0wNy0xOFQxMDowODowMi4zNzNa
        before:
          type:
          - string
          - 'null'
          example: MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa
      required:
      - after
      - before
      additionalProperties: false
      description: Cursors to the pages before and after current page. See the [Pagination](/api#pagination) section for reference.
  parameters:
    UserPathId:
      schema:
        $ref: '#/components/schemas/UserPathId'
      required: true
      description: ID of the User.
      name: userId
      in: path
    PaginationQueryBefore:
      schema:
        $ref: '#/components/schemas/PaginationQueryBefore'
      required: false
      description: Opaque cursor used to fetch previous page. Cannot be used together with `after`. Refer to [Pagination](/api#pagination) for more information.
      name: before
      in: query
    PathMeterId:
      schema:
        $ref: '#/components/schemas/PathMeterId'
      required: true
      description: The ID of the meter you are looking up
      name: meterId
      in: path
    PaginationQueryPageSize:
      schema:
        $ref: '#/components/schemas/PaginationQueryPageSize'
      required: false
      description: Number of records to return per page. Default page size is 50.
      name: pageSize
      in: query
    PaginationQueryAfter:
      schema:
        $ref: '#/components/schemas/PaginationQueryAfter'
      required: false
      description: Opaque cursor used to fetch next page. Cannot be set together with `before`. Refer to [Pagination](/api#pagination) for more information.
      name: after
      in: query
  securitySchemes:
    ClientAccessToken:
      type: oauth2
      description: 'A `ClientAccessToken` is obtained via the [OAuth 2.0 Client Credentials grant](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/) and carries authorization to access all functionalities and data in your Enode account.

        Full details at [The ClientAccessToken](/api#getting-an-access-token)

        '
      flows:
        clientCredentials:
          tokenUrl: https://oauth.production.enode.io/oauth2/token
          scopes: {}
x-provenance:
  method: harvested
  publisher: Enode
  source: https://enode-api.production.enode.io/openapi/v1.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)