openapi: 3.2.0
info:
  title: Green Button API Documentation Usage Point API
  description: Green Button API - ESPI 4.0
  version: 1.0.0
  contact:
    name: Green Button Alliance
    url: https://www.greenbuttonalliance.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-provenance: Shared Green Button Alliance OpenAPI documentation of the Green Button Connect My Data (CMD) ESPI API. NOT Alectra-authored and NOT an Alectra endpoint. Alectra Utilities publishes no first-party OpenAPI, no developer portal and no CMD base URI. It is included here because Alectra is a Green Button data custodian under Ontario Regulation 633/21 and its Green Button portal at https://alectrautilitiesgbportal.savagedata.com/ exposes the same /DataCustodian/espi/1_1/resource/ path shape described by this document -- though that could not be confirmed, because every path on that host (including a deliberately bogus control path) HTTP 302 redirects to /Connect/Authorize, a customer sign-in asking for account name and phone number. The servers[] entry below is the Green Button Alliance public sandbox, not Alectra.
  x-source-url: https://raw.githubusercontent.com/GreenButtonAlliance/OpenAPI-Green-Button-Documentation/main/green-button-openapi.json
  x-harvested: '2026-07-27'
  x-harvest-http-status: 200
  x-standard: Green Button / NAESB REQ.21 Energy Services Provider Interface (ESPI)
  x-mandate: Ontario Regulation 633/21 (Energy Data), filed 2021-09-02, in force 2021-11-01, implementation deadline 2023-11-01
servers:
- url: https://sandbox.greenbuttonalliance.org:8443/DataCustodian
  description: GBA Green Button Sandbox
security:
- oauth2: []
tags:
- name: UsagePoint
  description: Usage Point endpoints
paths:
  /espi/1_1/resource/UsagePoint:
    get:
      tags:
      - UsagePoint
      summary: Retrieve all Usage Points [FB_33]
      operationId: findUsagePoints
      parameters:
      - name: published-max
        in: query
        description: Maximum publication date (RFC 3339 instant)
        schema:
          type: string
          format: date
      - name: published-min
        in: query
        description: Minimum publication date (RFC 3339 instant)
        schema:
          type: string
          format: date
      - name: updated-max
        in: query
        description: Maximum update date (RFC 3339 instant)
        schema:
          type: string
          format: date
      - name: updated-min
        in: query
        description: Minimum update date (RFC 3339 instant)
        schema:
          type: string
          format: date
      - name: max-results
        in: query
        description: Maximum number of results to return
        schema:
          type: integer
          format: int64
      - name: start-index
        in: query
        description: Index of first result (1-indexed)
        schema:
          type: integer
          format: int64
      - name: depth
        in: query
        description: Response depth control
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          content:
            application/atom+xml:
              schema:
                $ref: '#/components/schemas/AtomFeed'
        '202':
          description: Accepted
          content:
            application/atom+xml:
              schema:
                $ref: '#/components/schemas/AtomFeed'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
  /espi/1_1/resource/UsagePoint/{usagePointId}:
    get:
      tags:
      - UsagePoint
      summary: Retrieve Usage Point by Id [FB_32]
      operationId: getUsagePoint
      parameters:
      - name: usagePointId
        in: path
        required: true
        description: Unique identifier for the UsagePoint resource
        schema:
          type: string
      - name: published-max
        in: query
        description: Maximum publication date (RFC 3339 instant)
        schema:
          type: string
          format: date
      - name: published-min
        in: query
        description: Minimum publication date (RFC 3339 instant)
        schema:
          type: string
          format: date
      - name: updated-max
        in: query
        description: Maximum update date (RFC 3339 instant)
        schema:
          type: string
          format: date
      - name: updated-min
        in: query
        description: Minimum update date (RFC 3339 instant)
        schema:
          type: string
          format: date
      - name: max-results
        in: query
        description: Maximum number of results to return
        schema:
          type: integer
          format: int64
      - name: start-index
        in: query
        description: Index of first result (1-indexed)
        schema:
          type: integer
          format: int64
      - name: depth
        in: query
        description: Response depth control
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          content:
            application/atom+xml:
              schema:
                $ref: '#/components/schemas/UsagePoint'
        '202':
          description: Accepted
          content:
            application/atom+xml:
              schema:
                $ref: '#/components/schemas/UsagePoint'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
components:
  schemas:
    AtomLink:
      type: object
      description: Atom link element (RFC 4287)
      xml:
        name: link
        namespace: http://www.w3.org/2005/Atom
      properties:
        href:
          type: string
          format: uri
          description: Link URI
        rel:
          type: string
          description: Link relationship type (e.g., 'self', 'up')
        type:
          type: string
          description: Media type (e.g., 'application/atom+xml')
    UsagePoint:
      type: object
      description: Logical point on a network at which consumption or production is measured or estimated
      xml:
        name: UsagePoint
        namespace: http://naesb.org/espi
      properties:
        roleFlags:
          type: string
          description: Specifies roles assigned to this usage point
        ServiceCategory:
          type: integer
          description: Category of service (0=electricity, 1=gas, 2=water, etc.)
        status:
          type: integer
          description: Current status (0=off, 1=on)
        isSdp:
          type: boolean
          description: Whether this is a service delivery point
        isVirtual:
          type: boolean
          description: Whether this is a virtual (logical) usage point
        connectionState:
          type: string
          description: Connection state relative to network
    AtomFeed:
      type: object
      description: Atom Feed (RFC 4287) containing ESPI resources
      xml:
        name: feed
        namespace: http://www.w3.org/2005/Atom
      properties:
        id:
          type: string
          format: uri
          description: Feed identifier
        title:
          type: string
          description: Feed title
        updated:
          type: string
          format: date-time
          description: ISO 8601 timestamp of last feed update
        link:
          type: array
          items:
            $ref: '#/components/schemas/AtomLink'
          description: Feed links (minimum 1 required per Atom spec)
        entry:
          type: array
          items:
            $ref: '#/components/schemas/AtomEntry'
          description: Feed entries containing ESPI resources
    AtomEntry:
      type: object
      description: Atom feed entry (RFC 4287) containing ESPI resource
      xml:
        name: entry
        namespace: http://www.w3.org/2005/Atom
      properties:
        id:
          type: string
          format: uri
          description: Unique entry identifier
        title:
          type: string
          description: Entry title
        published:
          type: string
          format: date-time
          description: ISO 8601 publication timestamp
        updated:
          type: string
          format: date-time
          description: ISO 8601 last update timestamp
        link:
          type: array
          items:
            $ref: '#/components/schemas/AtomLink'
          description: Entry links (minimum 2 required per Atom spec)
        content:
          $ref: '#/components/schemas/AtomContent'
    AtomContent:
      type: object
      description: Atom content element containing ESPI resource (RFC 4287)
      xml:
        name: content
        namespace: http://www.w3.org/2005/Atom
      properties:
        type:
          type: string
          description: Content media type (typically 'application/xml')
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://sandbox.greenbuttonalliance.org:8443/oauth/authorize
          tokenUrl: https://sandbox.greenbuttonalliance.org:8443/oauth/token
          scopes: {}
        clientCredentials:
          tokenUrl: https://sandbox.greenbuttonalliance.org:8443/oauth/token
          scopes: {}