openapi: 3.0.3
info:
  title: Xcel Energy Green Button Connect My Data ApplicationInformation EndDevice 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: EndDevice
  description: End devices managed by the meter (the meter itself and any subordinate devices).
paths:
  /edev:
    get:
      operationId: listEndDevices
      summary: List EndDevices
      description: Returns the EndDeviceList containing all EndDevices managed by the server.
      tags:
      - EndDevice
      security:
      - mtls: []
      parameters:
      - $ref: '#/components/parameters/StartIndex'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: EndDeviceList resource.
          content:
            application/sep+xml:
              schema:
                $ref: '#/components/schemas/EndDeviceList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createEndDevice
      summary: Register a new EndDevice
      description: Posts a new EndDevice resource to register a client with the server.
      tags:
      - EndDevice
      security:
      - mtls: []
      requestBody:
        required: true
        content:
          application/sep+xml:
            schema:
              $ref: '#/components/schemas/EndDevice'
      responses:
        '201':
          description: EndDevice created. The Location header contains the new resource URI.
          headers:
            Location:
              schema:
                type: string
              description: URI of the new EndDevice resource.
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /edev/{edevId}:
    get:
      operationId: getEndDevice
      summary: Get an EndDevice
      description: Returns a single EndDevice resource identified by edevId.
      tags:
      - EndDevice
      security:
      - mtls: []
      parameters:
      - $ref: '#/components/parameters/EdevId'
      responses:
        '200':
          description: EndDevice resource.
          content:
            application/sep+xml:
              schema:
                $ref: '#/components/schemas/EndDevice'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateEndDevice
      summary: Update an EndDevice
      description: Replaces an existing EndDevice resource.
      tags:
      - EndDevice
      security:
      - mtls: []
      parameters:
      - $ref: '#/components/parameters/EdevId'
      requestBody:
        required: true
        content:
          application/sep+xml:
            schema:
              $ref: '#/components/schemas/EndDevice'
      responses:
        '204':
          description: EndDevice updated successfully.
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteEndDevice
      summary: Delete an EndDevice
      tags:
      - EndDevice
      security:
      - mtls: []
      parameters:
      - $ref: '#/components/parameters/EdevId'
      responses:
        '204':
          description: EndDevice removed.
        '404':
          $ref: '#/components/responses/NotFound'
      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
    EdevId:
      name: edevId
      in: path
      required: true
      description: Numeric identifier of an EndDevice 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.
    EndDevice:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          sFDI:
            type: integer
            format: int64
            description: Short-form device identifier.
          lFDI:
            type: string
            description: Long-form device identifier (32 hex characters).
          deviceCategory:
            type: string
            description: Hex-encoded DeviceCategoryType.
          postRate:
            type: integer
          enabled:
            type: boolean
          changedTime:
            type: integer
          RegistrationLink:
            $ref: '#/components/schemas/Link'
          DeviceInformationLink:
            $ref: '#/components/schemas/Link'
          DeviceStatusLink:
            $ref: '#/components/schemas/Link'
          PowerStatusLink:
            $ref: '#/components/schemas/Link'
          LogEventListLink:
            $ref: '#/components/schemas/Link'
          ConfigurationLink:
            $ref: '#/components/schemas/Link'
          FunctionSetAssignmentsListLink:
            $ref: '#/components/schemas/Link'
    Link:
      type: object
      description: Link to another resource in the IEEE 2030.5 graph.
      properties:
        href:
          type: string
    EndDeviceList:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          all:
            type: integer
          results:
            type: integer
          EndDevice:
            type: array
            items:
              $ref: '#/components/schemas/EndDevice'
  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.