Xcel Energy Subscription API

openapi: 3.0.3
info:
  title: Xcel Energy Green Button Connect My Data ApplicationInformation Subscription API
  summary: OAuth 2.0 authorized customer energy usage data based on the NAESB ESPI standard.
  description: 'Xcel Energy Green Button Connect My Data API based on the ESPI (Energy Services Provider Interface) standard developed by NAESB. Enables authorized third-party applications to access customer electricity and natural gas usage data captured by Xcel Energy smart meters. Resources are exposed as Atom feeds and entries containing UsagePoint, MeterReading, IntervalBlock, ReadingType, ElectricPowerUsageSummary, ElectricPowerQualitySummary, LocalTimeParameters, and customer information. Customer authorization is granted via OAuth 2.0 and follows the Green Button Connect specification used by utilities across North America.

    '
  version: 1.1.0
  contact:
    name: Xcel Energy Developer Portal
    url: https://developer-apim.aws.xcelenergy.com/
  license:
    name: Proprietary
    url: https://www.xcelenergy.com/privacy_policy
  x-generated-from: documentation
  x-last-validated: '2026-05-03'
  x-standards:
  - NAESB ESPI 1.1
  - Green Button Connect My Data
servers:
- url: https://api.xcelenergy.com/DataCustodian/espi/1_1/resource
  description: Xcel Energy Data Custodian (Production)
- url: https://developer-apim.aws.xcelenergy.com/DataCustodian/espi/1_1/resource
  description: Xcel Energy Developer Sandbox
tags:
- name: Subscription
  description: Subscription/notification resources for resource-change events.
paths:
  /sub:
    get:
      operationId: listSubscriptions
      summary: List Subscriptions
      description: Returns the SubscriptionList describing client subscriptions to resource-change notifications.
      tags:
      - Subscription
      security:
      - mtls: []
      responses:
        '200':
          description: SubscriptionList resource.
          content:
            application/sep+xml:
              schema:
                $ref: '#/components/schemas/SubscriptionList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createSubscription
      summary: Create a Subscription
      tags:
      - Subscription
      security:
      - mtls: []
      requestBody:
        required: true
        content:
          application/sep+xml:
            schema:
              $ref: '#/components/schemas/Subscription'
      responses:
        '201':
          description: Subscription created.
          headers:
            Location:
              schema:
                type: string
              description: URI of the new Subscription resource.
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sub/{subId}:
    delete:
      operationId: deleteSubscription
      summary: Delete a Subscription
      tags:
      - Subscription
      security:
      - mtls: []
      parameters:
      - $ref: '#/components/parameters/SubId'
      responses:
        '204':
          description: Subscription removed.
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Resource:
      type: object
      description: Base IEEE 2030.5 Resource type that all resources inherit from.
      properties:
        href:
          type: string
          description: Stable URI of the resource.
    Subscription:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          subscribedResource:
            type: string
            description: URI of the resource being subscribed to.
          encoding:
            type: integer
            description: 0=application/sep+xml, 1=application/sep-exi.
          level:
            type: string
          limit:
            type: integer
          notificationURI:
            type: string
            description: Client URI to which Notification POSTs are delivered.
    SubscriptionList:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          all:
            type: integer
          results:
            type: integer
          Subscription:
            type: array
            items:
              $ref: '#/components/schemas/Subscription'
  parameters:
    SubId:
      name: subId
      in: path
      required: true
      description: Identifier of a Subscription resource.
      schema:
        type: integer
        minimum: 0
        example: 0
  responses:
    NotFound:
      description: The requested resource was not found.
    BadRequest:
      description: The request body or parameters were invalid.
  securitySchemes:
    accessToken:
      type: oauth2
      description: Customer-scoped access token issued via the OAuth 2.0 authorization-code grant.
      flows:
        authorizationCode:
          authorizationUrl: https://api.xcelenergy.com/DataCustodian/oauth/authorize
          tokenUrl: https://api.xcelenergy.com/DataCustodian/oauth/token
          refreshUrl: https://api.xcelenergy.com/DataCustodian/oauth/token
          scopes:
            FB=4_5_15;IntervalDuration=900;BlockDuration=monthly;HistoryLength=34128000: Standard ESPI scope string for 15-minute electric usage data with 13 months of history.
    clientAccessToken:
      type: oauth2
      description: Application-scoped client access token used for management endpoints (Authorization list, Bulk, ServiceStatus).
      flows:
        clientCredentials:
          tokenUrl: https://api.xcelenergy.com/DataCustodian/oauth/token
          scopes:
            DataCustodian_Admin_Access: Administrative scope used for application-level operations.
    registrationAccessToken:
      type: http
      scheme: bearer
      bearerFormat: Registration Access Token
      description: Token issued at application registration; used to read or update ApplicationInformation.