green-button-openapi.json

{
  "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"
    }
  },
  "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"}
        }
      }
    }
  }
}