openapi: 3.0.3
info:
  title: Xcel Energy Green Button Connect My Data ApplicationInformation UsagePoint 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: UsagePoint
  description: Logical metered points that produce energy usage data for a service.
paths:
  /Subscription/{subscriptionId}/UsagePoint:
    get:
      operationId: listUsagePoints
      summary: List UsagePoints for a subscription
      description: 'Returns an Atom feed of UsagePoint entries the customer has authorized for the subscription.

        '
      tags:
      - UsagePoint
      security:
      - accessToken: []
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      - $ref: '#/components/parameters/PublishedMin'
      - $ref: '#/components/parameters/PublishedMax'
      - $ref: '#/components/parameters/UpdatedMin'
      - $ref: '#/components/parameters/UpdatedMax'
      responses:
        '200':
          description: Atom feed of UsagePoint entries.
          content:
            application/atom+xml:
              schema:
                $ref: '#/components/schemas/UsagePointFeed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /Subscription/{subscriptionId}/UsagePoint/{usagePointId}:
    get:
      operationId: getUsagePoint
      summary: Retrieve a single UsagePoint
      description: Returns the UsagePoint entry identified by usagePointId.
      tags:
      - UsagePoint
      security:
      - accessToken: []
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      - $ref: '#/components/parameters/UsagePointId'
      responses:
        '200':
          description: Atom entry containing the UsagePoint resource.
          content:
            application/atom+xml:
              schema:
                $ref: '#/components/schemas/UsagePoint'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /upt:
    get:
      operationId: listUsagePoints
      summary: List read-only UsagePoints
      description: Returns the UsagePointList — meter-managed UsagePoints exposing read-only readings.
      tags:
      - UsagePoint
      security:
      - mtls: []
      responses:
        '200':
          description: UsagePointList resource.
          content:
            application/sep+xml:
              schema:
                $ref: '#/components/schemas/UsagePointList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /upt/{uptId}:
    get:
      operationId: getUsagePoint
      summary: Get a UsagePoint
      tags:
      - UsagePoint
      security:
      - mtls: []
      parameters:
      - $ref: '#/components/parameters/UptId'
      responses:
        '200':
          description: UsagePoint resource.
          content:
            application/sep+xml:
              schema:
                $ref: '#/components/schemas/UsagePoint_2'
        '404':
          $ref: '#/components/responses/NotFound_2'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /upt/{uptId}/mr:
    get:
      operationId: listMeterReadings
      summary: List MeterReadings for a UsagePoint
      tags:
      - UsagePoint
      security:
      - mtls: []
      parameters:
      - $ref: '#/components/parameters/UptId'
      responses:
        '200':
          description: MeterReadingList resource.
          content:
            application/sep+xml:
              schema:
                $ref: '#/components/schemas/MeterReadingList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /upt/{uptId}/mr/{mrId}/r:
    get:
      operationId: listReadings
      summary: List Readings for a MeterReading
      tags:
      - UsagePoint
      security:
      - mtls: []
      parameters:
      - $ref: '#/components/parameters/UptId'
      - $ref: '#/components/parameters/MrId'
      - $ref: '#/components/parameters/StartIndex'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: ReadingList resource.
          content:
            application/sep+xml:
              schema:
                $ref: '#/components/schemas/ReadingList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    Unauthorized:
      description: Authentication failed or the access token is invalid or expired.
    NotFound:
      description: The requested resource was not found or is not authorized for this token.
    Forbidden:
      description: The token type does not grant access to the requested endpoint or resource.
    NotFound_2:
      description: The requested resource was not found.
  schemas:
    Link:
      type: object
      description: Link to another resource in the IEEE 2030.5 graph.
      properties:
        href:
          type: string
    UsagePointFeed:
      allOf:
      - $ref: '#/components/schemas/AtomFeed'
    UsagePoint_2:
      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'
    AtomFeed:
      type: object
      description: Atom feed envelope used to wrap collections of ESPI resource entries.
      properties:
        id:
          type: string
        title:
          type: string
        updated:
          type: string
          format: date-time
        link:
          type: array
          items:
            type: object
            properties:
              rel:
                type: string
              href:
                type: string
        entry:
          type: array
          items:
            $ref: '#/components/schemas/AtomEntry'
    UsagePointList:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          all:
            type: integer
          results:
            type: integer
          UsagePoint:
            type: array
            items:
              $ref: '#/components/schemas/UsagePoint_2'
    UsagePoint:
      allOf:
      - $ref: '#/components/schemas/AtomEntry'
      - type: object
        description: Logical metered point producing energy usage data for a service.
        properties:
          roleFlags:
            type: string
            description: Hex-encoded RoleFlags bit field.
          serviceCategory:
            type: object
            properties:
              kind:
                type: integer
                description: 0=electricity, 1=gas, 2=water, 3=pressure, 4=heat, 5=cold, 6=communication, 7=time.
                example: 0
          status:
            type: integer
            description: UsagePoint status code.
          ServiceDeliveryPoint:
            type: object
            properties:
              tariffProfile:
                type: string
              customerAgreement:
                type: string
    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.
    ReadingList:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          all:
            type: integer
          results:
            type: integer
          Reading:
            type: array
            items:
              type: object
              properties:
                qualityFlags:
                  type: string
                timePeriod:
                  type: object
                  properties:
                    duration:
                      type: integer
                    start:
                      type: integer
                value:
                  type: integer
                consumptionBlock:
                  type: integer
                touTier:
                  type: integer
    AtomEntry:
      type: object
      description: Atom entry envelope used to wrap ESPI resource payloads.
      properties:
        id:
          type: string
          description: Stable URI for the entry.
        title:
          type: string
          description: Human-readable title of the entry.
        published:
          type: string
          format: date-time
          description: Time the entry was first published.
        updated:
          type: string
          format: date-time
          description: Time the entry was last updated.
        link:
          type: array
          description: Atom link relations (self, up, related).
          items:
            type: object
            properties:
              rel:
                type: string
                example: self
              href:
                type: string
                example: UsagePoint/1
        content:
          type: object
          description: ESPI XML payload content.
    MeterReadingList:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          all:
            type: integer
          results:
            type: integer
          MeterReading:
            type: array
            items:
              type: object
              properties:
                mRID:
                  type: string
                description:
                  type: string
                ReadingTypeLink:
                  $ref: '#/components/schemas/Link'
                ReadingListLink:
                  $ref: '#/components/schemas/Link'
                RPLTimeLink:
                  $ref: '#/components/schemas/Link'
  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
    UpdatedMax:
      name: updated-max
      in: query
      required: false
      description: Upper bound (inclusive) for the Atom entry updated timestamp.
      schema:
        type: string
        example: '2026-04-30T23:59:59Z'
    MrId:
      name: mrId
      in: path
      required: true
      description: Identifier of a MeterReading resource.
      schema:
        type: integer
        minimum: 0
        example: 0
    UpdatedMin:
      name: updated-min
      in: query
      required: false
      description: Lower bound (inclusive) for the Atom entry updated timestamp.
      schema:
        type: string
        example: '2026-01-01T00:00:00Z'
    StartIndex:
      name: s
      in: query
      required: false
      description: 0-based start index for paginated lists.
      schema:
        type: integer
        minimum: 0
        example: 0
    PublishedMax:
      name: published-max
      in: query
      required: false
      description: Upper bound (inclusive) for the Atom entry published timestamp, in epoch seconds or ISO 8601.
      schema:
        type: string
        example: '2026-04-30T23:59:59Z'
    UptId:
      name: uptId
      in: path
      required: true
      description: Identifier of a UsagePoint resource.
      schema:
        type: integer
        minimum: 0
        example: 0
    SubscriptionId:
      name: subscriptionId
      in: path
      required: true
      description: Identifier of a Subscription created from an Authorization.
      schema:
        type: string
        example: sub-5678
    UsagePointId:
      name: usagePointId
      in: path
      required: true
      description: Identifier of a UsagePoint within a Subscription.
      schema:
        type: string
        example: '1'
    PublishedMin:
      name: published-min
      in: query
      required: false
      description: Lower bound (inclusive) for the Atom entry published timestamp, in epoch seconds or ISO 8601.
      schema:
        type: string
        example: '2026-01-01T00:00:00Z'
  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.