openapi: 3.1.0
info:
  title: PG&E Share My Data API
  description: >-
    The PG&E Share My Data API provides customer-authorized access to energy
    usage data following the Energy Service Provider Interface (ESPI) standard
    and Green Button Connect My Data specification. Third-party companies can
    access interval data for both electricity and gas usage through RESTful
    web services with OAuth 2.0 authorization.
  version: '1.0'
servers:
  - url: https://api.pge.com
tags:
  - name: Authorization
    description: OAuth 2.0 authorization for customer data access.
  - name: Subscriptions
    description: Manage data subscriptions for customer accounts.
  - name: Usage
    description: Retrieve energy usage interval data.
paths:
  /GreenButtonConnect/espi/1_1/resource/Authorization:
    get:
      operationId: listAuthorizations
      summary: List authorizations
      description: >-
        Retrieves a list of active customer authorizations granting access
        to energy usage data for the authenticated third-party application.
      tags:
        - Authorization
      responses:
        '200':
          description: Success
  /GreenButtonConnect/espi/1_1/resource/Subscription:
    get:
      operationId: listSubscriptions
      summary: List subscriptions
      description: >-
        Retrieves a list of data subscriptions for authorized customer
        accounts with subscription status and details.
      tags:
        - Subscriptions
      responses:
        '200':
          description: Success
  /GreenButtonConnect/espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint:
    get:
      operationId: listUsagePoints
      summary: List usage points
      description: >-
        Retrieves usage points for a specified subscription, representing
        metering points for electricity or gas service.
      tags:
        - Usage
      parameters:
        - name: subscriptionId
          in: path
          required: true
          description: The subscription identifier.
          schema:
            type: string
      responses:
        '200':
          description: Success
  /GreenButtonConnect/espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/MeterReading:
    get:
      operationId: listMeterReadings
      summary: List meter readings
      description: >-
        Retrieves meter reading data for a specified usage point,
        containing interval usage data for electricity or gas.
      tags:
        - Usage
      parameters:
        - name: subscriptionId
          in: path
          required: true
          description: The subscription identifier.
          schema:
            type: string
        - name: usagePointId
          in: path
          required: true
          description: The usage point identifier.
          schema:
            type: string
      responses:
        '200':
          description: Success
  ? /GreenButtonConnect/espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/MeterReading/{meterReadingId}/IntervalBlock
  : get:
      operationId: listIntervalBlocks
      summary: List interval blocks
      description: >-
        Retrieves interval block data containing detailed energy
        consumption measurements at regular time intervals.
      tags:
        - Usage
      parameters:
        - name: subscriptionId
          in: path
          required: true
          description: The subscription identifier.
          schema:
            type: string
        - name: usagePointId
          in: path
          required: true
          description: The usage point identifier.
          schema:
            type: string
        - name: meterReadingId
          in: path
          required: true
          description: The meter reading identifier.
          schema:
            type: string
      responses:
        '200':
          description: Success
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.pge.com/datacustodian/oauth/v2/authorize
          tokenUrl: https://api.pge.com/datacustodian/oauth/v2/token
          scopes:
            usage:read: Read energy usage data