Client-supplied mirror usage points used to publish readings to the server.
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.