openapi: 3.1.0
info:
  title: Consumers Energy Green Button Connect My Data API (UtilityAPI)
  description: |
    Best-effort OpenAPI 3.1 description of UtilityAPI's REST surface for the
    Consumers Energy Green Button Connect My Data program. The API exposes
    authorizations, meters, bills, and interval/usage data, plus the
    Green Button XML batch resource. Authentication uses OAuth 2.0 (the
    Green Button OAuth flow); third parties must be pre-registered with
    Consumers Energy and use utility ID `CONSUMERSENERGY`.
  version: '2.0'
  contact:
    name: UtilityAPI - Consumers Energy
    url: https://utilityapi.com/docs/utilities/consumersenergy
servers:
  - url: https://utilityapi.com/api/v2
security:
  - oauth2: []
  - bearerAuth: []
paths:
  /authorizations:
    get:
      summary: List authorizations
      operationId: listAuthorizations
      tags: [Authorizations]
      responses:
        '200': { description: List of authorizations }
  /authorizations/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      summary: Get an authorization
      operationId: getAuthorization
      tags: [Authorizations]
      responses:
        '200': { description: Authorization details }
    delete:
      summary: Revoke an authorization
      operationId: deleteAuthorization
      tags: [Authorizations]
      responses:
        '204': { description: Authorization revoked }
  /meters:
    get:
      summary: List meters
      operationId: listMeters
      tags: [Meters]
      parameters:
        - in: query
          name: meters
          schema: { type: string }
          description: Filter by meter id(s).
      responses:
        '200': { description: List of meters }
  /meters/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      summary: Get a meter
      operationId: getMeter
      tags: [Meters]
      responses:
        '200': { description: Meter details }
  /bills:
    get:
      summary: List bills
      operationId: listBills
      tags: [Bills]
      parameters:
        - in: query
          name: meters
          schema: { type: string }
      responses:
        '200': { description: List of bills }
  /intervals:
    get:
      summary: List interval (usage) data
      operationId: listIntervals
      tags: [Intervals]
      parameters:
        - in: query
          name: meters
          schema: { type: string }
      responses:
        '200': { description: List of intervals }
  /DataCustodian/espi/1_1/resource/Batch/Subscription/{subscriptionId}/UsagePoint/{usagePointId}:
    parameters:
      - in: path
        name: subscriptionId
        required: true
        schema: { type: string }
      - in: path
        name: usagePointId
        required: true
        schema: { type: string }
    get:
      summary: Green Button ESPI batch resource
      description: |
        Retrieves Green Button ESPI 1.1 batch XML for the given subscription
        and usage point. Returned as application/atom+xml.
      operationId: getEspiBatch
      tags: [GreenButton]
      responses:
        '200':
          description: ESPI batch XML
          content:
            application/atom+xml: {}
components:
  parameters:
    Id:
      in: path
      name: id
      required: true
      schema: { type: string }
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://utilityapi.com/authorize
          tokenUrl: https://utilityapi.com/api/v2/oauth/token
          scopes:
            auth-sso: Production single-sign-on scope (Consumers Energy)
    bearerAuth:
      type: http
      scheme: bearer