openapi: 3.0.3
info:
  title: Xcel Energy Green Button Connect My Data ApplicationInformation DER 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: DER
  description: Distributed Energy Resource programs, controls, and settings.
paths:
  /derp:
    get:
      operationId: listDERPrograms
      summary: List DER programs
      description: Returns the DERProgramList — programs that schedule controls for distributed energy resources such as PV and storage.
      tags:
      - DER
      security:
      - mtls: []
      parameters:
      - $ref: '#/components/parameters/StartIndex'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: DERProgramList resource.
          content:
            application/sep+xml:
              schema:
                $ref: '#/components/schemas/DERProgramList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /derp/{derpId}:
    get:
      operationId: getDERProgram
      summary: Get a DER program
      tags:
      - DER
      security:
      - mtls: []
      parameters:
      - $ref: '#/components/parameters/DerpId'
      responses:
        '200':
          description: DERProgram resource.
          content:
            application/sep+xml:
              schema:
                $ref: '#/components/schemas/DERProgram'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /derp/{derpId}/derc:
    get:
      operationId: listDERControls
      summary: List DERControls for a DER program
      tags:
      - DER
      security:
      - mtls: []
      parameters:
      - $ref: '#/components/parameters/DerpId'
      responses:
        '200':
          description: DERControlList resource.
          content:
            application/sep+xml:
              schema:
                $ref: '#/components/schemas/DERControlList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /der:
    get:
      operationId: listDERs
      summary: List Distributed Energy Resources
      tags:
      - DER
      security:
      - mtls: []
      parameters:
      - $ref: '#/components/parameters/StartIndex'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: DERList resource.
          content:
            application/sep+xml:
              schema:
                $ref: '#/components/schemas/DERList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    Limit:
      name: l
      in: query
      required: false
      description: Maximum number of list items to return.
      schema:
        type: integer
        minimum: 1
        maximum: 255
        example: 25
    DerpId:
      name: derpId
      in: path
      required: true
      description: Identifier of a DERProgram resource.
      schema:
        type: integer
        minimum: 0
        example: 0
    StartIndex:
      name: s
      in: query
      required: false
      description: 0-based start index for paginated lists.
      schema:
        type: integer
        minimum: 0
        example: 0
  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.
    Link:
      type: object
      description: Link to another resource in the IEEE 2030.5 graph.
      properties:
        href:
          type: string
    DERList:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          all:
            type: integer
          results:
            type: integer
          DER:
            type: array
            items:
              type: object
              properties:
                AssociatedDERProgramListLink:
                  $ref: '#/components/schemas/Link'
                AssociatedUsagePointLink:
                  $ref: '#/components/schemas/Link'
                CurrentDERProgramLink:
                  $ref: '#/components/schemas/Link'
                DERAvailabilityLink:
                  $ref: '#/components/schemas/Link'
                DERStatusLink:
                  $ref: '#/components/schemas/Link'
                DERSettingsLink:
                  $ref: '#/components/schemas/Link'
                DERCapabilityLink:
                  $ref: '#/components/schemas/Link'
    DERProgramList:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          all:
            type: integer
          results:
            type: integer
          DERProgram:
            type: array
            items:
              $ref: '#/components/schemas/DERProgram'
    DERProgram:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          mRID:
            type: string
          description:
            type: string
          version:
            type: integer
          primacy:
            type: integer
          DefaultDERControlLink:
            $ref: '#/components/schemas/Link'
          DERControlListLink:
            $ref: '#/components/schemas/Link'
          DERCurveListLink:
            $ref: '#/components/schemas/Link'
          ActiveDERControlListLink:
            $ref: '#/components/schemas/Link'
    DERControlList:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          all:
            type: integer
          results:
            type: integer
          DERControl:
            type: array
            items:
              type: object
              properties:
                mRID:
                  type: string
                description:
                  type: string
                creationTime:
                  type: integer
                EventStatus:
                  type: object
                  properties:
                    currentStatus:
                      type: integer
                    dateTime:
                      type: integer
                    potentiallySuperseded:
                      type: boolean
                interval:
                  type: object
                  properties:
                    duration:
                      type: integer
                    start:
                      type: integer
                randomizeStart:
                  type: integer
                randomizeDuration:
                  type: integer
                DERControlBase:
                  type: object
                  description: DERControlBase parameter set (opModConnect
                  opModEnergize: null
                  opModFixedPFAbsorbW: null
                  opModMaxLimW: null
                  etc.).: null
  responses:
    NotFound:
      description: The requested resource was not found.
  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.