{
  "openapi": "3.0.0",
  "info": {
    "title": "Green Button API Documentation",
    "description": "Green Button API - ESPI 4.0",
    "version": "1.0.0",
    "contact": {
      "name": "Green Button Alliance",
      "url": "https://www.greenbuttonalliance.org"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "x-provenance": "Shared Green Button Alliance OpenAPI documentation of the Green Button Connect My Data (CMD) ESPI API. NOT Alectra-authored and NOT an Alectra endpoint. Alectra Utilities publishes no first-party OpenAPI, no developer portal and no CMD base URI. It is included here because Alectra is a Green Button data custodian under Ontario Regulation 633/21 and its Green Button portal at https://alectrautilitiesgbportal.savagedata.com/ exposes the same /DataCustodian/espi/1_1/resource/ path shape described by this document -- though that could not be confirmed, because every path on that host (including a deliberately bogus control path) HTTP 302 redirects to /Connect/Authorize, a customer sign-in asking for account name and phone number. The servers[] entry below is the Green Button Alliance public sandbox, not Alectra.",
    "x-source-url": "https://raw.githubusercontent.com/GreenButtonAlliance/OpenAPI-Green-Button-Documentation/main/green-button-openapi.json",
    "x-harvested": "2026-07-27",
    "x-harvest-http-status": 200,
    "x-standard": "Green Button / NAESB REQ.21 Energy Services Provider Interface (ESPI)",
    "x-mandate": "Ontario Regulation 633/21 (Energy Data), filed 2021-09-02, in force 2021-11-01, implementation deadline 2023-11-01"
  },
  "servers": [
    {
      "url": "https://sandbox.greenbuttonalliance.org:8443/DataCustodian",
      "description": "GBA Green Button Sandbox"
    }
  ],
  "components": {
    "schemas": {
      "ApplicationInformation": {
        "type": "object",
        "description": "Contains information about a Third Party Application requesting access to DataCustodian services",
        "xml": {
          "name": "ApplicationInformation",
          "namespace": "http://naesb.org/espi"
        },
        "properties": {
          "dataCustodianId": {
            "type": "string",
            "description": "Identifier for the Data Custodian"
          },
          "dataCustodianApplicationStatus": {
            "type": "integer",
            "description": "Current status of the application (provided by Data Custodian)"
          },
          "thirdPartyApplicationDescription": {
            "type": "string",
            "description": "Description of the Third Party Application"
          },
          "thirdPartyApplicationStatus": {
            "type": "integer",
            "description": "Current status of the Third Party Application"
          },
          "thirdPartyApplicationType": {
            "type": "integer",
            "description": "Type of application (1=Web, 2=Desktop, 3=Mobile, 4=Device)"
          },
          "thirdPartyApplicationUse": {
            "type": "integer",
            "description": "Expected use of the application"
          },
          "client_name": {
            "type": "string",
            "description": "Name of the application (OAuth client_name)"
          },
          "client_id": {
            "type": "string",
            "description": "Identifier for the Third Party (OAuth client_id)"
          },
          "client_secret": {
            "type": "string",
            "description": "Secret for the client (OAuth client_secret)"
          },
          "redirect_uri": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "OAuth redirect URIs"
          },
          "scope": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "OAuth scopes"
          },
          "grant_types": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Supported OAuth grant types"
          }
        }
      },
      "Authorization": {
        "type": "object",
        "description": "Represents a permission granted by an owner for access to a resource",
        "xml": {
          "name": "Authorization",
          "namespace": "http://naesb.org/espi"
        },
        "properties": {
          "status": {
            "type": "integer",
            "description": "Status of the authorization (0=Revoked, 1=Active, 2=Denied)"
          },
          "expires_at": {
            "type": "integer",
            "format": "int64",
            "description": "Expiration period for the access token (Unix timestamp)"
          },
          "grant_type": {
            "type": "string",
            "description": "Type of grant being negotiated"
          },
          "scope": {
            "type": "string",
            "description": "Negotiated scope of the authorization"
          },
          "token_type": {
            "type": "string",
            "description": "Type of token (Bearer)"
          },
          "resourceURI": {
            "type": "string",
            "format": "uri",
            "description": "URI to access the authorized resource"
          },
          "authorizationURI": {
            "type": "string",
            "format": "uri",
            "description": "URI to update or delete this authorization"
          },
          "customerResourceURI": {
            "type": "string",
            "format": "uri",
            "description": "URI to access PII data authorized for this customer"
          }
        }
      },
      "UsagePoint": {
        "type": "object",
        "description": "Logical point on a network at which consumption or production is measured or estimated",
        "xml": {
          "name": "UsagePoint",
          "namespace": "http://naesb.org/espi"
        },
        "properties": {
          "roleFlags": {
            "type": "string",
            "description": "Specifies roles assigned to this usage point"
          },
          "ServiceCategory": {
            "type": "integer",
            "description": "Category of service (0=electricity, 1=gas, 2=water, etc.)"
          },
          "status": {
            "type": "integer",
            "description": "Current status (0=off, 1=on)"
          },
          "isSdp": {
            "type": "boolean",
            "description": "Whether this is a service delivery point"
          },
          "isVirtual": {
            "type": "boolean",
            "description": "Whether this is a virtual (logical) usage point"
          },
          "connectionState": {
            "type": "string",
            "description": "Connection state relative to network"
          }
        }
      },
      "AtomLink": {
        "type": "object",
        "description": "Atom link element (RFC 4287)",
        "xml": {
          "name": "link",
          "namespace": "http://www.w3.org/2005/Atom"
        },
        "properties": {
          "href": {
            "type": "string",
            "format": "uri",
            "description": "Link URI"
          },
          "rel": {
            "type": "string",
            "description": "Link relationship type (e.g., 'self', 'up')"
          },
          "type": {
            "type": "string",
            "description": "Media type (e.g., 'application/atom+xml')"
          }
        }
      },
      "AtomContent": {
        "type": "object",
        "description": "Atom content element containing ESPI resource (RFC 4287)",
        "xml": {
          "name": "content",
          "namespace": "http://www.w3.org/2005/Atom"
        },
        "properties": {
          "type": {
            "type": "string",
            "description": "Content media type (typically 'application/xml')"
          }
        }
      },
      "AtomEntry": {
        "type": "object",
        "description": "Atom feed entry (RFC 4287) containing ESPI resource",
        "xml": {
          "name": "entry",
          "namespace": "http://www.w3.org/2005/Atom"
        },
        "properties": {
          "id": {
            "type": "string",
            "format": "uri",
            "description": "Unique entry identifier"
          },
          "title": {
            "type": "string",
            "description": "Entry title"
          },
          "published": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 publication timestamp"
          },
          "updated": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 last update timestamp"
          },
          "link": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AtomLink"
            },
            "description": "Entry links (minimum 2 required per Atom spec)"
          },
          "content": {
            "$ref": "#/components/schemas/AtomContent"
          }
        }
      },
      "AtomFeed": {
        "type": "object",
        "description": "Atom Feed (RFC 4287) containing ESPI resources",
        "xml": {
          "name": "feed",
          "namespace": "http://www.w3.org/2005/Atom"
        },
        "properties": {
          "id": {
            "type": "string",
            "format": "uri",
            "description": "Feed identifier"
          },
          "title": {
            "type": "string",
            "description": "Feed title"
          },
          "updated": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of last feed update"
          },
          "link": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AtomLink"
            },
            "description": "Feed links (minimum 1 required per Atom spec)"
          },
          "entry": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AtomEntry"
            },
            "description": "Feed entries containing ESPI resources"
          }
        }
      }
    },
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://sandbox.greenbuttonalliance.org:8443/oauth/authorize",
            "tokenUrl": "https://sandbox.greenbuttonalliance.org:8443/oauth/token",
            "scopes": {}
          },
          "clientCredentials": {
            "tokenUrl": "https://sandbox.greenbuttonalliance.org:8443/oauth/token",
            "scopes": {}
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": []
    }
  ],
  "tags": [
    {
      "name": "ApplicationInformation",
      "description": "Application Information endpoints"
    },
    {
      "name": "Authorization",
      "description": "Authorization endpoints"
    },
    {
      "name": "Batch",
      "description": "Batch data transfer endpoints"
    },
    {
      "name": "UsagePoint",
      "description": "Usage Point endpoints"
    }
  ],
  "paths": {
    "/espi/1_1/resource/ApplicationInformation": {
      "get": {
        "tags": [
          "ApplicationInformation"
        ],
        "summary": "Retrieve all Application Information [FB_33]",
        "operationId": "findApplicationInformations",
        "parameters": [
          {
            "name": "published-max",
            "in": "query",
            "description": "Maximum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "published-min",
            "in": "query",
            "description": "Minimum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-max",
            "in": "query",
            "description": "Maximum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-min",
            "in": "query",
            "description": "Minimum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "max-results",
            "in": "query",
            "description": "Maximum number of results to return",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "start-index",
            "in": "query",
            "description": "Index of first result (1-indexed)",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Response depth control",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/espi/1_1/resource/ApplicationInformation/{applicationInformationId}": {
      "get": {
        "tags": [
          "ApplicationInformation"
        ],
        "summary": "Retrieve Application Information by Id [FB_3]",
        "operationId": "getApplicationInformation",
        "parameters": [
          {
            "name": "applicationInformationId",
            "in": "path",
            "required": true,
            "description": "Unique identifier for the ApplicationInformation resource",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/ApplicationInformation"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/ApplicationInformation"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/espi/1_1/resource/Authorization": {
      "get": {
        "tags": [
          "Authorization"
        ],
        "summary": "Find all Authorizations [FB_3]",
        "operationId": "findAuthorizations",
        "parameters": [
          {
            "name": "published-max",
            "in": "query",
            "description": "Maximum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "published-min",
            "in": "query",
            "description": "Minimum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-max",
            "in": "query",
            "description": "Maximum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-min",
            "in": "query",
            "description": "Minimum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "max-results",
            "in": "query",
            "description": "Maximum number of results to return",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "start-index",
            "in": "query",
            "description": "Index of first result (1-indexed)",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Response depth control",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/espi/1_1/resource/Authorization/{authorizationId}": {
      "get": {
        "tags": [
          "Authorization"
        ],
        "summary": "Retrieve Authorization by Id [FB_3]",
        "operationId": "getAuthorization",
        "parameters": [
          {
            "name": "authorizationId",
            "in": "path",
            "required": true,
            "description": "Unique identifier for the Authorization resource",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "published-max",
            "in": "query",
            "description": "Maximum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "published-min",
            "in": "query",
            "description": "Minimum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-max",
            "in": "query",
            "description": "Maximum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-min",
            "in": "query",
            "description": "Minimum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "max-results",
            "in": "query",
            "description": "Maximum number of results to return",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "start-index",
            "in": "query",
            "description": "Index of first result (1-indexed)",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Response depth control",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/Authorization"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/Authorization"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/espi/1_1/resource/Batch/Bulk/{bulkId}": {
      "get": {
        "tags": [
          "Batch"
        ],
        "summary": "Request Bulk transfer [FB_35]",
        "operationId": "downloadBulkData",
        "parameters": [
          {
            "name": "bulkId",
            "in": "path",
            "required": true,
            "description": "Unique identifier for the Bulk transfer",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "published-max",
            "in": "query",
            "description": "Maximum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "published-min",
            "in": "query",
            "description": "Minimum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-max",
            "in": "query",
            "description": "Maximum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-min",
            "in": "query",
            "description": "Minimum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "max-results",
            "in": "query",
            "description": "Maximum number of results to return",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "start-index",
            "in": "query",
            "description": "Index of first result (1-indexed)",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Response depth control",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/espi/1_1/resource/UsagePoint": {
      "get": {
        "tags": [
          "UsagePoint"
        ],
        "summary": "Retrieve all Usage Points [FB_33]",
        "operationId": "findUsagePoints",
        "parameters": [
          {
            "name": "published-max",
            "in": "query",
            "description": "Maximum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "published-min",
            "in": "query",
            "description": "Minimum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-max",
            "in": "query",
            "description": "Maximum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-min",
            "in": "query",
            "description": "Minimum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "max-results",
            "in": "query",
            "description": "Maximum number of results to return",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "start-index",
            "in": "query",
            "description": "Index of first result (1-indexed)",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Response depth control",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/espi/1_1/resource/UsagePoint/{usagePointId}": {
      "get": {
        "tags": [
          "UsagePoint"
        ],
        "summary": "Retrieve Usage Point by Id [FB_32]",
        "operationId": "getUsagePoint",
        "parameters": [
          {
            "name": "usagePointId",
            "in": "path",
            "required": true,
            "description": "Unique identifier for the UsagePoint resource",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "published-max",
            "in": "query",
            "description": "Maximum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "published-min",
            "in": "query",
            "description": "Minimum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-max",
            "in": "query",
            "description": "Maximum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-min",
            "in": "query",
            "description": "Minimum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "max-results",
            "in": "query",
            "description": "Maximum number of results to return",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "start-index",
            "in": "query",
            "description": "Index of first result (1-indexed)",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Response depth control",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/UsagePoint"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/UsagePoint"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    }
  }
}