API Evangelist enhancements for the Green Button ESPI contract as implemented by PG&E

# authorship: generated by API Evangelist tooling. Stamped 2026-08-18
# on the file's own generator header (roadmap#64). An unmarked file is
# NOT assumed to be ours -- absence of evidence was never stamped.
x-method: generated
overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Green Button ESPI contract as implemented by PG&E
  version: 1.0.0
extends: openapi/green-button-alliance-espi-openapi.json
x-generated: '2026-07-27'
x-method: generated
x-source: >-
  Generated by the API Evangelist enrichment pipeline on 2026-07-27 from PG&E's
  own published documents (third-party developer page, Supported-APIs.pdf,
  Supported-Function-Block-Scope-String-Mapping-Click-Thru-2.0.pdf) and live
  anonymous probes of api.pge.com. The base document is the Green Button
  Alliance's OpenAPI for the ESPI standard, whose declared server is the GBA
  sandbox; this overlay records what is true of PG&E's PRODUCTION
  implementation. It never mutates the harvested original.
actions:
  - target: $.info
    update:
      x-apievangelist-provider: Pacific Gas and Electric
      x-apievangelist-provider-slug: pge
      x-apievangelist-first-party: false
      x-apievangelist-note: >-
        PG&E publishes no first-party OpenAPI. This document describes the NAESB
        REQ.21 ESPI standard that PG&E Share My Data implements. PG&E's
        production resource set is larger than the seven paths here and is
        enumerated in PG&E Supported-APIs.pdf.
      x-apievangelist-artifacts:
        authentication: authentication/pge-authentication.yml
        scopes: scopes/pge-scopes.yml
        conventions: conventions/pge-conventions.yml
        errors: errors/pge-problem-types.yml
        rate_limits: rate-limits/pge-rate-limits.yml
        lifecycle: lifecycle/pge-lifecycle.yml
        changelog: changelog/pge-changelog.yml
        sandbox: sandbox/pge-sandbox.yml
        webhooks: asyncapi/pge-share-my-data-notifications.yml
        data_model: data-model/pge-data-model.yml
        conformance: conformance/pge-conformance.yml
  - target: $.servers
    update:
      - url: https://api.pge.com/GreenButtonConnect
        description: >-
          PG&E Share My Data production ESPI gateway (MuleSoft). Verified live
          anonymously on 2026-07-27 — resource paths return HTTP 400 "Invalid
          Certificate" while invented sibling paths return HTTP 404 "No listener
          for endpoint". Requires mutual TLS 1.2 with a CA-issued client X.509
          certificate in addition to a bearer token.
        x-apievangelist-verified: '2026-07-27'
        x-apievangelist-access: application-approval gated; not self-serve
  - target: $.info
    update:
      x-apievangelist-oauth:
        authorization_endpoint_production: https://sharemydata.pge.com/myAuthorization
        token_endpoint_production: https://api.pge.com/datacustodian/oauth/v2/token
        authorization_endpoint_test: https://api.pge.com/datacustodian/test/oauth/v2/authorize
        token_endpoint_test: https://api.pge.com/datacustodian/test/oauth/v2/token
        grants: [authorization_code, client_credentials, refresh_token]
        openid_connect: false
        scope_model: >-
          ESPI function-block scope string (FB=...;AdditionalScope=...), not
          named OAuth scopes. See scopes/pge-scopes.yml.
        token_lifetime_seconds: 3600
        authorization_code_lifetime_seconds: 600
        refresh_token_lifetime: 1 year
      x-apievangelist-rate-limits:
        per_vendor_requests_per_second: 1
        per_client_id_requests_per_hour: 2000
        per_client_id_requests_per_day: 20000
        daily_reset: 17:00 America/Los_Angeles
        source: rate-limits/pge-rate-limits.yml
      x-apievangelist-query-conventions:
        date_format: Zulu (UTC) only
        parameters: [published-min, published-max, updated-min, updated-max, correlationID]
        source: conventions/pge-conventions.yml
  - target: $.paths['/espi/1_1/resource/ApplicationInformation/{applicationInformationId}'].get
    update:
      x-apievangelist-pge-token-class: registration_access_token
      x-apievangelist-pge-path: https://api.pge.com/GreenButtonConnect/espi/1_1/resource/ApplicationInformation/{ApplicationInformationID}
  - target: $.paths['/espi/1_1/resource/Authorization'].get
    update:
      x-apievangelist-pge-token-class: client_access_token
      x-apievangelist-pge-path: https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization
  - target: $.paths['/espi/1_1/resource/Authorization/{authorizationId}'].get
    update:
      x-apievangelist-pge-token-class: client_access_token
      x-apievangelist-pge-note: >-
        PG&E also supports HTTP DELETE on this resource to revoke an
        authorization; the Green Button Alliance document declares only GET.
  - target: $.paths['/espi/1_1/resource/Batch/Bulk/{bulkId}'].get
    update:
      x-apievangelist-pge-token-class: client_access_token
      x-apievangelist-pge-async: >-
        Asynchronous. PG&E acknowledges the request and announces the prepared
        result to the third party's registered Notification URI as an
        ns0:BatchList document. See asyncapi/pge-share-my-data-notifications.yml.
      x-apievangelist-pge-function-block: FB=35 (REST for Bulk), FB=39 (Push model)
  - target: $.paths['/espi/1_1/resource/UsagePoint'].get
    update:
      x-apievangelist-pge-token-class: access_token (per customer)
      x-apievangelist-pge-path: >-
        PG&E nests UsagePoint under a Subscription:
        /espi/1_1/resource/Subscription/{SubscriptionID}/UsagePoint
      x-apievangelist-pge-function-block: FB=32 (Resource Level REST)
  - target: $.paths['/espi/1_1/resource/UsagePoint/{usagePointId}'].get
    update:
      x-apievangelist-pge-token-class: access_token (per customer)
      x-apievangelist-pge-path: >-
        PG&E nests UsagePoint under a Subscription:
        /espi/1_1/resource/Subscription/{SubscriptionID}/UsagePoint/{UsagePointID}