openapi: 3.0.3
info:
  title: Xcel Energy Green Button Connect My Data ApplicationInformation MirrorUsagePoint 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: MirrorUsagePoint
  description: Client-supplied mirror usage points used to publish readings to the server.
paths:
  /mup:
    get:
      operationId: listMirrorUsagePoints
      summary: List MirrorUsagePoints
      description: Returns the MirrorUsagePointList — client-supplied mirror points used to publish readings to the server.
      tags:
      - MirrorUsagePoint
      security:
      - mtls: []
      responses:
        '200':
          description: MirrorUsagePointList resource.
          content:
            application/sep+xml:
              schema:
                $ref: '#/components/schemas/MirrorUsagePointList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createMirrorUsagePoint
      summary: Create a MirrorUsagePoint
      description: Posts a new MirrorUsagePoint to publish readings.
      tags:
      - MirrorUsagePoint
      security:
      - mtls: []
      requestBody:
        required: true
        content:
          application/sep+xml:
            schema:
              $ref: '#/components/schemas/MirrorUsagePoint'
      responses:
        '201':
          description: MirrorUsagePoint created.
          headers:
            Location:
              schema:
                type: string
              description: URI of the new MirrorUsagePoint resource.
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /mup/{mupId}:
    post:
      operationId: postMirrorMeterReading
      summary: Publish a MirrorMeterReading
      description: Posts a MirrorMeterReading containing readings to be published against the MirrorUsagePoint.
      tags:
      - MirrorUsagePoint
      security:
      - mtls: []
      parameters:
      - $ref: '#/components/parameters/MupId'
      requestBody:
        required: true
        content:
          application/sep+xml:
            schema:
              $ref: '#/components/schemas/MirrorMeterReading'
      responses:
        '201':
          description: Mirror reading accepted.
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    BadRequest:
      description: The request body or parameters were invalid.
  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.
    MirrorUsagePointList:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          all:
            type: integer
          results:
            type: integer
          MirrorUsagePoint:
            type: array
            items:
              $ref: '#/components/schemas/MirrorUsagePoint'
    MirrorMeterReading:
      type: object
      properties:
        mRID:
          type: string
        description:
          type: string
        lastUpdateTime:
          type: integer
        nextUpdateTime:
          type: integer
        ReadingType:
          type: object
          properties:
            accumulationBehaviour:
              type: integer
            commodity:
              type: integer
            dataQualifier:
              type: integer
            flowDirection:
              type: integer
            intervalLength:
              type: integer
            kind:
              type: integer
            phase:
              type: integer
            powerOfTenMultiplier:
              type: integer
            uom:
              type: integer
        Reading:
          type: object
          properties:
            timePeriod:
              type: object
              properties:
                duration:
                  type: integer
                start:
                  type: integer
            value:
              type: integer
        MirrorReadingSet:
          type: array
          items:
            type: object
            properties:
              mRID:
                type: string
              timePeriod:
                type: object
                properties:
                  duration:
                    type: integer
                  start:
                    type: integer
              Reading:
                type: array
                items:
                  type: object
                  properties:
                    timePeriod:
                      type: object
                      properties:
                        duration:
                          type: integer
                        start:
                          type: integer
                    value:
                      type: integer
                    qualityFlags:
                      type: string
    Link:
      type: object
      description: Link to another resource in the IEEE 2030.5 graph.
      properties:
        href:
          type: string
    UsagePoint:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          mRID:
            type: string
          description:
            type: string
          version:
            type: integer
          roleFlags:
            type: string
            description: Hex-encoded RoleFlagsType bit field.
          serviceCategoryKind:
            type: integer
            description: 0=electricity, 1=gas, 2=water, 3=pressure, 4=heat, 5=cold, 6=communication, 7=time.
          status:
            type: integer
          MeterReadingListLink:
            $ref: '#/components/schemas/Link'
    MirrorUsagePoint:
      allOf:
      - $ref: '#/components/schemas/UsagePoint'
      - type: object
        properties:
          deviceLFDI:
            type: string
            description: LFDI of the device publishing the readings.
          postRate:
            type: integer
          MirrorMeterReading:
            type: array
            items:
              $ref: '#/components/schemas/MirrorMeterReading'
  parameters:
    MupId:
      name: mupId
      in: path
      required: true
      description: Identifier of a MirrorUsagePoint resource.
      schema:
        type: integer
        minimum: 0
        example: 0
  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.