Every API here is available over the APIs.io API and to AI agents over MCP.
{
"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": "Harvested verbatim from the Green Button Alliance OpenAPI-Green-Button-Documentation repository. This is the STANDARD contract (NAESB REQ.21 ESPI) that PG&E Share My Data implements. It is NOT authored or published by Pacific Gas and Electric Company, and its declared server is the Green Button Alliance public sandbox, NOT a PG&E host. PG&E publishes no first-party OpenAPI. PG&E production ESPI resources live under https://api.pge.com/GreenButtonConnect/espi/1_1/resource/ and are enumerated in PG&E Supported-APIs.pdf.",
"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-not-a-pge-host": true
},
"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"
}
}
}
}
}
}