Green Button API

https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API
Admin
The Green Button API provides access to REST services for Data Custodian and Third Party...
Tokens:42,838
Snippets:130
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### GET /espi/1_1/resource/UsagePoint/

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Retrieve all Usage Points. This endpoint allows clients to fetch a list of all available Usage Points.

```APIDOC
## GET /espi/1_1/resource/UsagePoint/

### Description
Retrieve all Usage Points. This endpoint allows clients to fetch a list of all available Usage Points, with options for filtering and pagination.

### Method
GET

### Endpoint
/espi/1_1/resource/UsagePoint/

### Parameters

#### Query Parameters
- **published-max** (Date) - Optional - The upper bound on the published date of the Usage Point.
- **published-min** (Date) - Optional - The lower bound on the published date of the Usage Point.
- **updated-max** (Date) - Optional - The upper bound on the updated date of the Usage Point.
- **updated-min** (Date) - Optional - The lower bound on the updated date of the Usage Point.
- **max-results** (long) - Optional - The upper bound on the number of entries to be contained in a reply.
- **start-index** (long) - Optional - The one-based offset in the DataCustodian's collection of referenced resources that should be transferred as the first entry of this response.
- **depth** (long) - Optional - The maximum number of entries to be transferred in the response.

### Request Example
```
GET /espi/1_1/resource/UsagePoint/?published-max=2023-10-27&max-results=100 HTTP/1.1
Host: example.com
Authorization: Bearer data_custodian_access_token
```

### Response
#### Success Response (200)
- **Usage Points** (Array) - A list of Usage Point resources.

#### Response Example
```json
{
  "usagePoints": [
    {
      "id": "usagePoint123",
      "name": "Main Residence"
    },
    {
      "id": "usagePoint456",
      "name": "Detached Garage"
    }
  ]
}
```

#### Error Responses
- **400 Bad Request**: The request was malformed.
- **403 Forbidden**: The provided access token is invalid or insufficient.

```

--------------------------------

### GET /espi/1_1/resource/MeterReading

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Retrieves a list of meter readings with various filtering and pagination options.

```APIDOC
## GET /espi/1_1/resource/MeterReading

### Description
Retrieves a list of meter readings with various filtering and pagination options.

### Method
GET

### Endpoint
/espi/1_1/resource/MeterReading

### Parameters
#### Query Parameters
- **published-max** (Date) - Optional - The upper bound on the published date of the Meter Reading.
- **published-min** (Date) - Optional - The lower bound on the published date of the Meter Reading.
- **updated-max** (Date) - Optional - The upper bound on the updated date of the Meter Reading.
- **updated-min** (Date) - Optional - The lower bound on the updated date of the Meter Reading.
- **max-results** (long) - Optional - The upper bound on the number of entries to be contained in a reply.
- **start-index** (long) - Optional - The one based offset in the Data Custodian's collection of Meter Readings that should be transferred as the first entry of the response.
- **depth** (long) - Optional - The maximum number of entries to be transferred in the response.

### Response
#### Success Response (200)
- **meterReadingId** (string) - Description not available.

#### Response Example
{
  "meterReadingId": "string"
}
```

--------------------------------

### GET /espi/1_1/resource/Batch/RetailCustomer/{retailCustomerId}/UsagePoint

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Retrieves a Green Button XML file for a specific UsagePoint associated with a RetailCustomer.

```APIDOC
## GET /espi/1_1/resource/Batch/RetailCustomer/{retailCustomerId}/UsagePoint

### Description
Download a Green Button XML file containing a specific UsagePoint for this RetailCustomer [FB_33].

### Method
GET

### Endpoint
/espi/1_1/resource/Batch/RetailCustomer/{retailCustomerId}/UsagePoint

### Parameters
#### Path Parameters
- **retailCustomerId** (String) - Required - The Retail Customer's Id

#### Query Parameters
- **published-max** (Date) - Optional - The upper bound on the published date of the Green Button XML file request.
- **published-min** (Date) - Optional - The lower bound on the published date of the Green Button XML file request.
- **updated-max** (Date) - Optional - The upper bound on the updated date of the Green Button XML file request.
- **updated-min** (Date) - Optional - The lower bound on the updated date of the Green Button XML file request.
- **max-results** (long) - Optional - The upper bound on the number of entries to be contained in a reply to this response.
- **start-index** (long) - Optional - The one based offset in the DataCustodian's collection of Green Button XML file request that should be transferred as the first entry of this request.
- **depth** (long) - Optional - The maximum number of entries to be transferred in the response to this request.

### Request Example
(No example provided in source)

### Response
#### Success Response (200)
(No specific fields detailed in source)

#### Response Example
(No example provided in source)
```

--------------------------------

### GET /espi/1_1/resource/ApplicationInformation

Source: https://context7.com/context7/greenbuttonalliance_github_io_openespi-greenbutton-api-documentation_api/llms.txt

Retrieves a list of all registered third-party application information structures. Supports filtering by publication/update dates and pagination.

```APIDOC
## GET /espi/1_1/resource/ApplicationInformation

### Description
Retrieves a list of all registered third-party application information structures. Supports filtering by publication/update dates and pagination.

### Method
GET

### Endpoint
/espi/1_1/resource/ApplicationInformation

### Query Parameters
- **updated-min** (string) - Optional - Filter applications updated on or after this date-time.
- **max-results** (integer) - Optional - The maximum number of entries to return.
- **start-index** (integer) - Optional - The starting index of the entry list.

### Request Example
```bash
curl -X GET "https://api.example.com/espi/1_1/resource/ApplicationInformation?updated-min=2024-09-14T00:00:00Z&max-results=10&start-index=1" \
  -H "Authorization: Bearer 2a85f4bd-30db-4b7d-8f41-b046b0566cb3" \
  -H "Accept: application/atom+xml"
```

### Response
#### Success Response (200)
- **feed** (object) - Atom feed containing ApplicationInformation entries.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <entry>
    <id>urn:uuid:app-123</id>
    <published>2024-10-01T10:00:00Z</published>
    <updated>2024-10-10T15:30:00Z</updated>
    <content type="application/xml">
      <ApplicationInformation>
        <dataCustodianId>DC001</dataCustodianId>
        <clientName>EnergyAnalytics Pro</clientName>
      </ApplicationInformation>
    </content>
  </entry>
</feed>
```
```

--------------------------------

### GET /espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerQualitySummary

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Retrieves all Electric Power Quality Summaries associated with a specific Usage Point within a Subscription. This endpoint allows for filtering by publication and update dates, as well as controlling the number of results and starting index.

```APIDOC
## GET /espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerQualitySummary

### Description
Retrieve all Electric Power Quality Summaries for a given Usage Point within a Subscription. Supports filtering by date ranges and pagination.

### Method
GET

### Endpoint
/espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerQualitySummary

### Parameters
#### Path Parameters
- **subscriptionId** (String) - Required - The Subscription's Id
- **usagePointId** (String) - Required - The UsagePoint's Id

#### Query Parameters
- **published-max** (Date) - Optional - The upper bound on the published date of the Subscription.
- **published-min** (Date) - Optional - The lower bound on the published date of the Subscription.
- **updated-max** (Date) - Optional - The upper bound on the updated date of the Subscription.
- **updated-min** (Date) - Optional - The lower bound on the updated date of the Subscription.
- **max-results** (long) - Optional - The upper bound on the number of entries to be contained in a reply to this response.
- **start-index** (long) - Optional - The one based offset in the Data Custodian's collection of Subscriptions that should be transferred as the first entry of this request.
- **depth** (long) - Optional - The maximum number of entries to be transferred in the response to this request.

### Response
#### Success Response (200)
- **Response Body** (XML) - An XML representation of all Electric Power Quality Summaries.

#### Response Example
(XML content would be detailed here if available)

### Error Handling
- **400 Bad Request**
- **403 Forbidden**
```

--------------------------------

### GET /management

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Resets the Data Custodian Database to a known state, including pre-configured UsagePoints and access tokens.

```APIDOC
## GET /management

### Description
Resets the Data Custodian Database to a known state, including pre-configured UsagePoints and access tokens.

### Method
GET

### Endpoint
/management

### Parameters
#### Query Parameters
- **command** (String) - Required - The Data Custodian management command to be issued

### Response
#### Success Response (200)
- (object) - OK

#### Success Response (202)
- (object) - Accepted
```

--------------------------------

### GET /espi/1_1/resource/Batch/Subscription/{subscriptionId}

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Requests a Greenbutton Subscription from a Data Custodian.

```APIDOC
## GET /espi/1_1/resource/Batch/Subscription/{subscriptionId}

### Description
Requests a Greenbutton Subscription from a Data Custodian.

### Method
GET

### Endpoint
/espi/1_1/resource/Batch/Subscription/{subscriptionId}

### Parameters
#### Path Parameters
- **subscriptionId** (string) - Required - The ID of the subscription to retrieve.

### Response
#### Success Response
- **Description**: Returns the requested subscription details.

#### Error Response
- **Description**: Handles potential errors during the request.
```

--------------------------------

### GET /espi/1_1/resource/Authorization

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Retrieves a list of all Data Custodian Authorizations. Supports filtering by publication and update dates, and pagination.

```APIDOC
## GET /espi/1_1/resource/Authorization

### Description
Find all Data Custodian Authorizations [FB_3]. Returns an XML representation of all Authorizations. Requires a Bearer access token.

### Method
GET

### Endpoint
/espi/1_1/resource/Authorization

### Parameters
#### Path Parameters
None

#### Query Parameters
- **published-max** (Date) - Optional - The upper bound on the published date of the Authorization.
- **published-min** (Date) - Optional - The lower bound on the published date of the Authorization.
- **updated-max** (Date) - Optional - The upper bound on the updated date of the Authorization.
- **updated-min** (Date) - Optional - The lower bound on the updated date of the Authorization.
- **max-results** (long) - Optional - The upper bound on the number of entries to be contained in a reply to this response.
- **start-index** (long) - Optional - The one based offset in the DataCustodian's collection of Authorizations that should be transferred as the first entry of this request.
- **depth** (long) - Optional - The maximum number of entries to be transferred in the response to this request.

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Success** - OK
#### Response Example
None
```

--------------------------------

### GET /espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerUsageSummary

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Retrieves all Electric Power Usage Summaries for a given Usage Point and Subscription. Returns an XML representation of the summaries.

```APIDOC
## GET /espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerUsageSummary

### Description
Retrieves all Electric Power Usage Summaries.

### Method
GET

### Endpoint
`/espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerUsageSummary`

### Parameters
#### Path Parameters
- **subscriptionId** (String) - Required - The Subscription's Id
- **usagePointId** (string) - Required - Id of the UsagePoint.

### Response
#### Success Response (200)
- **(XML representation of Electric Power Usage Summaries)**

#### Response Example
```xml
<feed>
  <!-- Electric Power Usage Summary entries -->
</feed>
```

#### Error Responses
- **(No specific error responses mentioned, but standard HTTP errors may apply)**
```

--------------------------------

### GET /espi/1_1/resource/Batch/Bulk/{bulkId}

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Requests a Bulk transfer from a Data Custodian. Supports filtering by published and updated dates, and pagination.

```APIDOC
## GET /espi/1_1/resource/Batch/Bulk/{bulkId}

### Description
Requests a Bulk transfer from a Data Custodian.

### Method
GET

### Endpoint
/espi/1_1/resource/Batch/Bulk/{bulkId}

### Parameters
#### Path Parameters
- **bulkId** (String) - Required - The Bulk Id as specified in the OAuth2 SCOPE string.

#### Query Parameters
- **published-max** (Date) - Optional - The upper bound on the published date of the Bulk request.
- **published-min** (Date) - Optional - The lower bound on the published date of the Bulk request.
- **updated-max** (Date) - Optional - The upper bound on the updated date of the Bulk request.
- **updated-min** (Date) - Optional - The lower bound on the updated date of the Bulk request.
- **max-results** (long) - Optional - The upper bound on the number of entries to be contained in a reply to this response.
- **start-index** (long) - Optional - The one based offset in the DataCustodian's collection of Bulk request that should be transferred as the first entry of this request.
- **depth** (long) - Optional - The maximum number of entries to be transferred in the response to this request.

### Response
#### Success Response (200, 202)
- **Status**: OK or Accepted

#### Error Response (400, 403)
- **Status**: Bad Request or Forbidden
```

--------------------------------

### Retrieve Electric Power Quality Summaries

Source: https://context7.com/context7/greenbuttonalliance_github_io_openespi-greenbutton-api-documentation_api/llms.txt

Retrieves all power quality summary records for a specific usage point. This GET request requires an Authorization header and an Accept header for application/atom+xml. An optional 'updated-min' query parameter can filter results by update time.

```bash
# Get all power quality summaries for usage point
curl -X GET "https://api.example.com/espi/1_1/resource/Subscription/5/UsagePoint/up-001/ElectricPowerQualitySummary?updated-min=2024-09-01T00:00:00Z" \
  -H "Authorization: Bearer f48223ce-92f5-4a41-9028-1a370eb102c5" \
  -H "Accept: application/atom+xml"
```

--------------------------------

### GET /espi/1_1/resource/Batch/Bulk/{bulkId}

Source: https://context7.com/context7/greenbuttonalliance_github_io_openespi-greenbutton-api-documentation_api/llms.txt

Initiates retrieval of bulk energy usage data for multiple retail customers using a bulk identifier. Supports batch data exports and allows filtering by update time and number of results.

```APIDOC
## GET /espi/1_1/resource/Batch/Bulk/{bulkId}

### Description
Initiates retrieval of bulk energy usage data for multiple retail customers using a bulk identifier. Supports batch data exports and allows filtering by update time and number of results.

### Method
GET

### Endpoint
`/espi/1_1/resource/Batch/Bulk/{bulkId}`

### Parameters
#### Path Parameters
- **bulkId** (string) - Required - The identifier for the bulk data set.

#### Query Parameters
- **updated-min** (string) - Optional - Filters data updated after this timestamp (ISO 8601 format).
- **max-results** (integer) - Optional - The maximum number of results to return.

### Request Example
```bash
curl -X GET "https://api.example.com/espi/1_1/resource/Batch/Bulk/bulk-001?updated-min=2024-10-01T00:00:00Z&max-results=100" \
  -H "Authorization: Bearer 2a85f4bd-30db-4b7d-8f41-b046b0566cb3" \
  -H "Accept: application/atom+xml"
```

### Response
#### Success Response (200)
- **feed** (object) - Atom feed containing bulk energy usage data.
  - **id** (string) - Unique identifier for the feed.
  - **entry** (array) - Array of entries, each representing a piece of data (e.g., RetailCustomer, UsagePoint).

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>urn:uuid:bulk-001</id>
  <entry><!-- RetailCustomer 1 data --></entry>
  <entry><!-- RetailCustomer 2 data --></entry>
  <entry><!-- UsagePoint data --></entry>
</feed>
```

#### Error Response
- **202 Accepted**: The request is accepted, but processing is still in progress.
- **400 Bad Request**: Invalid bulk identifier provided.
```

--------------------------------

### GET /espi/1_1/resource/Batch/Subscription/{subscriptionId}/UsagePoint/{usagePointId}

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Requests a Green Button Subscription from a Data Custodian for a specific Usage Point.

```APIDOC
## GET /espi/1_1/resource/Batch/Subscription/{subscriptionId}/UsagePoint/{usagePointId}

### Description
Request a Greenbutton Subscription from a DataCustodian [FB_32].

### Method
GET

### Endpoint
/espi/1_1/resource/Batch/Subscription/{subscriptionId}/UsagePoint/{usagePointId}

### Parameters
#### Path Parameters
- **subscriptionId** (String) - Required - The Subscription's Id
- **usagePointId** (String) - Required - The Usage Point's Id

#### Query Parameters
- **published-max** (Date) - Optional - The upper bound on the published date of the Subscription.
- **published-min** (Date) - Optional - The lower bound on the published date of the Subscription.
- **updated-max** (Date) - Optional - The upper bound on the updated date of the Subscription.
- **updated-min** (Date) - Optional - The lower bound on the updated date of the Subscription.
- **max-results** (long) - Optional - The upper bound on the number of entries to be contained in a reply to this response.
- **start-index** (long) - Optional - The one based offset in the DataCustodian's collection of Subscriptions that should be transferred as the first entry of this request.
- **depth** (long) - Optional - The maximum number of entries to be transferred in the response to this request.

### Request Example
(No example provided in source)

### Response
#### Success Response (200)
(No specific fields detailed in source)

#### Response Example
(No example provided in source)
```

--------------------------------

### GET /espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerQualitySummary/{electricPowerQualitySummaryId}

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Retrieves a specific Electric Power Quality Summary for a given Usage Point and Subscription. Supports filtering by published and updated dates, as well as pagination.

```APIDOC
## GET /espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerQualitySummary/{electricPowerQualitySummaryId}

### Description
Retrieves a specific Electric Power Quality Summary resource.

### Method
GET

### Endpoint
`/espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerQualitySummary/{electricPowerQualitySummaryId}`

### Parameters
#### Path Parameters
- **subscriptionId** (String) - Required - The Subscription's Id
- **usagePointId** (string) - Required - Id of the Usage Point the Electric Power Quality Summary references.
- **electricPowerQualitySummaryId** (string) - Required - Id of the Electric Power Quality Summary to be retrieved.

#### Query Parameters
- **published-max** (Date) - Optional - The upper bound on the published date of the referenced resource
- **published-min** (Date) - Optional - The lower bound on the published date of the referenced resource
- **updated-max** (Date) - Optional - The upper bound on the updated date of the referenced resource
- **updated-min** (Date) - Optional - The lower bound on the updated date of the referenced resource
- **max-results** (long) - Optional - The upper bound on the number of entries to be contained in a reply to this response
- **start-index** (long) - Optional - The one based offset in the Data Custodian's collection of referenced resources that should be transferred as the first entry of this request.
- **depth** (long) - Optional - The maximum number of entries to be transferred in the response to this request

### Response
#### Success Response (200)
- **(No specific fields mentioned, typically returns Electric Power Quality Summary data)**

#### Response Example
```json
{
  "example": "Electric Power Quality Summary data"
}
```

#### Error Responses
- **400 Bad Request**
- **403 Forbidden**
```

--------------------------------

### Retrieve Subscription Data - GET /Batch/Subscription/{id}

Source: https://context7.com/context7/greenbuttonalliance_github_io_openespi-greenbutton-api-documentation_api/llms.txt

Fetches all energy usage data associated with a specific subscription ID. This returns complete usage information in Green Button XML format for the subscribed retail customer. The `depth=all` parameter can be used to retrieve all related data.

```shell
curl -X GET "https://api.example.com/espi/1_1/resource/Batch/Subscription/5?depth=all" \
  -H "Authorization: Bearer f48223ce-92f5-4a41-9028-1a370eb102c5" \
  -H "Accept: application/atom+xml"
```

--------------------------------

### GET /management?command=reset

Source: https://context7.com/context7/greenbuttonalliance_github_io_openespi-greenbutton-api-documentation_api/llms.txt

Resets the sandbox Data Custodian database to its initial state. This includes preconfigured usage points, access tokens, and authorizations, useful for testing purposes.

```APIDOC
## GET /management?command=reset

### Description
Non-standard management endpoint that resets the sandbox Data Custodian database to initial state with preconfigured usage points, access tokens, and authorizations for testing purposes.

### Method
GET

### Endpoint
`/management`

### Parameters
#### Query Parameters
- **command** (string) - Required - Specifies the management command to execute. Must be `reset` for this operation.

### Request Example
```bash
curl -X GET "https://api.example.com/management?command=reset" \
  -H "Authorization: Bearer 2a85f4bd-30db-4b7d-8f41-b046b0566cb3"
```

### Response
#### Success Response (200 OK)
- **Response Body** (string) - Confirmation message indicating the database has been reset.

#### Response Example
```
Database reset to initial state with test data
```

### Available Commands
- **reset**: Restores database to default testing configuration.
- **backup**: Creates snapshot of current database state.
- **restore**: Restores from latest backup snapshot.

#### Error Response (403 Forbidden)
- Returned if the request is missing the `data_custodian_access_token`.

#### Error Response (400 Bad Request)
- Returned if an invalid command parameter is provided.
```
```

--------------------------------

### GET /espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerQualitySummary/{electricPowerQualitySummaryId}

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Retrieves a specific Electric Power Quality Summary using its unique identifier. This allows for fetching detailed information about a single power quality summary entry.

```APIDOC
## GET /espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerQualitySummary/{electricPowerQualitySummaryId}

### Description
Retrieve a specific Electric Power Quality Summary using its Id.

### Method
GET

### Endpoint
/espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerQualitySummary/{electricPowerQualitySummaryId}

### Parameters
#### Path Parameters
- **subscriptionId** (String) - Required - The Subscription's Id
- **usagePointId** (String) - Required - Id of the UsagePoint the Electric Power Quality Summary references.
- **electricPowerQualitySummaryId** (String) - Required - The unique identifier of the Electric Power Quality Summary to retrieve.

### Response
#### Success Response (200)
- **Response Body** (XML) - An XML representation of the requested Electric Power Quality Summary.

#### Response Example
(XML content would be detailed here if available)

### Error Handling
- **400 Bad Request**
- **403 Forbidden**
```

--------------------------------

### Retrieve Electric Power Usage Summary

Source: https://context7.com/context7/greenbuttonalliance_github_io_openespi-greenbutton-api-documentation_api/llms.txt

Fetches power usage summary records for a usage point. This GET request requires an Authorization header and an Accept header for application/atom+xml. Query parameters like 'published-min' and 'max-results' can be used for filtering and pagination.

```bash
# Get power usage summaries for billing period
curl -X GET "https://api.example.com/espi/1_1/resource/Subscription/5/UsagePoint/up-001/ElectricPowerUsageSummary?published-min=2024-09-01T00:00:00Z&max-results=12" \
  -H "Authorization: Bearer f48223ce-92f5-4a41-9028-1a370eb102c5" \
  -H "Accept: application/atom+xml"
```

--------------------------------

### GET /espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerUsageSummary

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Retrieves a collection of Electric Power Usage Summaries for a given Usage Point within a Subscription. Supports filtering by published and updated dates, as well as pagination and result limits.

```APIDOC
## GET /espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerUsageSummary

### Description
Retrieves a collection of Electric Power Usage Summaries for a given Usage Point within a Subscription. Supports filtering by published and updated dates, as well as pagination and result limits.

### Method
GET

### Endpoint
/espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerUsageSummary

### Parameters
#### Path Parameters
- **subscriptionId** (String) - Required - The Subscription's Id
- **usagePointId** (string) - Required - Id of the UsagePoint the Electric Power Usage Summary references.

#### Query Parameters
- **published-max** (Date) - Optional - The upper bound on the published date of the referenced resource
- **published-min** (Date) - Optional - The lower bound on the published date of the referenced resource
- **updated-max** (Date) - Optional - The upper bound on the updated date of the referenced resource
- **updated-min** (Date) - Optional - The lower bound on the updated date of the referenced resource
- **max-results** (long) - Optional - The upper bound on the number of entries to be contained in a reply to this response
- **start-index** (long) - Optional - The one based offset in the DataCustodian's collection of referenced resources that should be transferred as the first entry of this request.
- **depth** (long) - Optional - The maximum number of entries to be transferred in the response to this request

### Response
#### Success Response (200)
- **(No specific fields documented)** - OK
#### Success Response (202)
- **(No specific fields documented)** - Accepted

#### Error Response
- **(No specific fields documented)** - Bad Request (400)
- **(No specific fields documented)** - Forbidden (403)
```

--------------------------------

### GET /espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerUsageSummary

Source: https://context7.com/context7/greenbuttonalliance_github_io_openespi-greenbutton-api-documentation_api/llms.txt

Fetches power usage summary records including billing determinants and aggregated consumption data for a usage point.

```APIDOC
## GET /espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerUsageSummary

### Description
Fetches power usage summary records containing billing determinants, tariff information, and aggregated consumption data for a usage point.

### Method
GET

### Endpoint
/espi/1_1/resource/Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerUsageSummary

#### Path Parameters
- **subscriptionId** (string) - Required - The ID of the subscription.
- **usagePointId** (string) - Required - The ID of the usage point.

#### Query Parameters
- **published-min** (string) - Optional - Filter results to include records published after this timestamp (ISO 8601 format).
- **max-results** (integer) - Optional - The maximum number of results to return.

### Request Example
```bash
curl -X GET "https://api.example.com/espi/1_1/resource/Subscription/5/UsagePoint/up-001/ElectricPowerUsageSummary?published-min=2024-09-01T00:00:00Z&max-results=12" \
  -H "Authorization: Bearer f48223ce-92f5-4a41-9028-1a370eb102c5" \
  -H "Accept: application/atom+xml"
```

### Response
#### Success Response (200 OK)
- **feed** (xml) - An Atom feed containing ElectricPowerUsageSummary entries.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <entry>
    <content type="application/xml">
      <ElectricPowerUsageSummary>
        <billLastPeriod>15000</billLastPeriod>
        <billToDate>12500</billToDate>
        <costAdditionalLastPeriod>200</costAdditionalLastPeriod>
        <currency>840</currency>
        <billingPeriod><duration>2678400</duration><start>1693526400</start></billingPeriod>
      </ElectricPowerUsageSummary>
    </content>
  </entry>
</feed>
```

```

--------------------------------

### Request Bulk Transfer - GET /Batch/Bulk/{id}

Source: https://context7.com/context7/greenbuttonalliance_github_io_openespi-greenbutton-api-documentation_api/llms.txt

Initiates retrieval of bulk energy usage data for multiple retail customers using a bulk identifier. This supports batch data exports and is useful for obtaining historical energy consumption data. The request supports query parameters for filtering by update time and limiting results.

```shell
curl -X GET "https://api.example.com/espi/1_1/resource/Batch/Bulk/bulk-001?updated-min=2024-10-01T00:00:00Z&max-results=100" \
  -H "Authorization: Bearer 2a85f4bd-30db-4b7d-8f41-b046b0566cb3" \
  -H "Accept: application/atom+xml"
```

--------------------------------

### GET /espi/1_1/resource/Batch/Subscription/{subscriptionId}

Source: https://context7.com/context7/greenbuttonalliance_github_io_openespi-greenbutton-api-documentation_api/llms.txt

Fetches all energy usage data associated with a specific subscription ID, returning complete usage information in Green Button XML format for the subscribed retail customer.

```APIDOC
## GET /espi/1_1/resource/Batch/Subscription/{subscriptionId}

### Description
Fetches all energy usage data associated with a specific subscription ID, returning complete usage information in Green Button XML format for the subscribed retail customer.

### Method
GET

### Endpoint
`/espi/1_1/resource/Batch/Subscription/{subscriptionId}`

### Parameters
#### Path Parameters
- **subscriptionId** (string) - Required - The unique identifier of the subscription.

#### Query Parameters
- **depth** (string) - Optional - Specifies the depth of related data to retrieve (e.g., "all").

### Request Example
```bash
curl -X GET "https://api.example.com/espi/1_1/resource/Batch/Subscription/5?depth=all" \
  -H "Authorization: Bearer f48223ce-92f5-4a41-9028-1a370eb102c5" \
  -H "Accept: application/atom+xml"
```

### Response
#### Success Response (200)
- **feed** (object) - Atom feed containing subscription energy usage data.
  - **id** (string) - Unique identifier for the feed.
  - **entry** (array) - Array of entries, each representing a data record (e.g., UsagePoint, MeterReading).
    - **link** (object) - Link to related data.
      - **rel** (string) - Relationship type (e.g., "related").
      - **href** (string) - URL to the related resource.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>urn:uuid:subscription-5</id>
  <entry>
    <content type="application/xml">
      <UsagePoint>
        <serviceCategory><kind>0</kind></serviceCategory>
        <status>1</status>
      </UsagePoint>
    </content>
    <link rel="related" href="MeterReading/1"/>
  </entry>
</feed>
```

#### Error Response
- **403 Forbidden**: The provided token does not match the subscription.
```

--------------------------------

### Retrieve All Application Information (Bash)

Source: https://context7.com/context7/greenbuttonalliance_github_io_openespi-greenbutton-api-documentation_api/llms.txt

Retrieves a list of all registered third-party application information structures. Supports filtering by publication/update dates and pagination. Requires an Authorization header and Accept header for Atom/XML.

```bash
# Retrieve all applications updated in last 30 days with pagination
curl -X GET "https://api.example.com/espi/1_1/resource/ApplicationInformation?updated-min=2024-09-14T00:00:00Z&max-results=10&start-index=1" \
  -H "Authorization: Bearer 2a85f4bd-30db-4b7d-8f41-b046b0566cb3" \
  -H "Accept: application/atom+xml"

# Expected Response: HTTP 200 OK
# <?xml version="1.0" encoding="UTF-8"?>
# <feed xmlns="http://www.w3.org/2005/Atom">
#   <entry>
#     <id>urn:uuid:app-123</id>
#     <published>2024-10-01T10:00:00Z</published>
#     <updated>2024-10-10T15:30:00Z</updated>
#     <content type="application/xml">
#       <ApplicationInformation>
#         <dataCustodianId>DC001</dataCustodianId>
#         <clientName>EnergyAnalytics Pro</clientName>
#       </ApplicationInformation>
#     </content>
#   </entry>
# </feed>
```

--------------------------------

### Create New Application Information (Bash)

Source: https://context7.com/context7/greenbuttonalliance_github_io_openespi-greenbutton-api-documentation_api/llms.txt

Registers a new third-party application by submitting its metadata in Atom/XML format. Requires an Authorization header and Content-Type header set to application/atom+xml. Returns HTTP 201 Created on success.

```bash
# Register new third-party application
curl -X POST "https://api.example.com/espi/1_1/resource/ApplicationInformation" \
  -H "Authorization: Bearer 2a85f4bd-30db-4b7d-8f41-b046b0566cb3" \
  -H "Content-Type: application/atom+xml" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <content type="application/xml">
    <ApplicationInformation>
      <dataCustodianId>DC001</dataCustodianId>
      <clientName>Smart Home Manager</clientName>
      <clientId>client-789</clientId>
      <clientSecret>secret-xyz</clientSecret>
      <redirectUri>https://smarthome.example.com/callback</redirectUri>
      <scope>FB=1_3_4_5_13_14_15_19_27_28_29_30_31_32_33_34_35_37_38_39_40_41</scope>
    </ApplicationInformation>
  </content>
</entry>'

# Expected Response: HTTP 201 Created
# Location: /espi/1_1/resource/ApplicationInformation/app-789
```

--------------------------------

### GET /espi/1_1/resource/ReadServiceStatus

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Obtain the Data Custodian Resource Server's Status.

```APIDOC
## GET /espi/1_1/resource/ReadServiceStatus

### Description
Obtain the Data Custodian Resource Server's Status. This endpoint provides information about the operational status of the data custodian.

### Method
GET

### Endpoint
/espi/1_1/resource/ReadServiceStatus

### Parameters

#### Query Parameters
None

### Request Example
```
GET /espi/1_1/resource/ReadServiceStatus HTTP/1.1
Host: example.com
Authorization: Bearer data_custodian_access_token
```

### Response
#### Success Response (200)
- **Status** (string) - The current status of the service.

#### Response Example
```json
{
  "status": "Operational"
}
```

#### Error Responses
- **400 Bad Request**: The request was malformed.
- **403 Forbidden**: The provided access token is invalid or insufficient.

```

--------------------------------

### POST /espi/1_1/resource/Batch/RetailCustomer/{retailCustomerId}/UsagePoint

Source: https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/index

Uploads a Green Button XML file for a specific UsagePoint associated with a RetailCustomer.

```APIDOC
## POST /espi/1_1/resource/Batch/RetailCustomer/{retailCustomerId}/UsagePoint

### Description
Upload a Green Button XML file [FB_33].

### Method
POST

### Endpoint
/espi/1_1/resource/Batch/RetailCustomer/{retailCustomerId}/UsagePoint

### Parameters
#### Path Parameters
- **retailCustomerId** (String) - Required - The Retail Customer's Id

#### Request Body
- **xmlFile** (string) - Required - Contents of the file being uploaded. Parameter content type: application/xml

### Request Example
(No example provided in source)

### Response
#### Success Response (201)
(No specific fields detailed in source)

#### Response Example
(No example provided in source)
```

--------------------------------

### POST /espi/1_1/resource/Batch/RetailCustomer/{customerId}/UsagePoint

Source: https://context7.com/context7/greenbuttonalliance_github_io_openespi-greenbutton-api-documentation_api/llms.txt

Uploads usage data for a retail customer. This endpoint allows for the batch submission of energy usage information.

```APIDOC
## POST /espi/1_1/resource/Batch/RetailCustomer/{customerId}/UsagePoint

### Description
Uploads usage data for a retail customer. This endpoint allows for the batch submission of energy usage information.

### Method
POST

### Endpoint
/espi/1_1/resource/Batch/RetailCustomer/{customerId}/UsagePoint

#### Path Parameters
- **customerId** (string) - Required - The unique identifier for the retail customer.

#### Request Body
- **feed** (xml) - Required - An Atom feed containing UsagePoint and MeterReading entries.

### Request Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <entry>
    <content type="application/xml">
      <UsagePoint>
        <serviceCategory><kind>0</kind></serviceCategory>
        <status>1</status>
      </UsagePoint>
    </content>
  </entry>
  <entry>
    <content type="application/xml">
      <MeterReading>
        <ReadingType><powerOfTenMultiplier>0</powerOfTenMultiplier></ReadingType>
      </MeterReading>
    </content>
  </entry>
</feed>
```

### Response
#### Success Response (201 Created)
- **Location** (string) - The URL of the newly created usage point.

#### Response Example
```
Location: /espi/1_1/resource/RetailCustomer/customer-123/UsagePoint/up-new
```

#### Error Response (400 Bad Request)
- Description: Schema validation failed.

```

--------------------------------

### POST /espi/1_1/resource/Batch/Bulk/{bulkId}

Source: https://context7.com/context7/greenbuttonalliance_github_io_openespi-greenbutton-api-documentation_api/llms.txt

Uploads a Green Button XML file containing energy usage data for multiple customers in bulk format to the Data Custodian's system.

```APIDOC
## POST /espi/1_1/resource/Batch/Bulk/{bulkId}

### Description
Uploads a Green Button XML file containing energy usage data for multiple customers in bulk format to the Data Custodian's system.

### Method
POST

### Endpoint
`/espi/1_1/resource/Batch/Bulk/{bulkId}`

### Parameters
#### Path Parameters
- **bulkId** (string) - Required - The identifier for the bulk data set.

#### Request Body
- **XML File** (file) - Required - The Green Button XML file containing the bulk data.

### Request Example
```bash
curl -X POST "https://api.example.com/espi/1_1/resource/Batch/Bulk/bulk-001" \
  -H "Authorization: Bearer 03909715-b0ca-4797-9a9a-601fff1d2848" \
  -H "Content-Type: application/xml" \
  -d @bulk_usage_data.xml
```

### Request Body Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <entry>
    <content>
      <UsagePoint>
        <serviceCategory><kind>0</kind></serviceCategory>
      </UsagePoint>
    </content>
  </entry>
  <entry>
    <content>
      <MeterReading>
        <!-- meter reading data -->
      </MeterReading>
    </content>
  </entry>
</feed>
```

### Response
#### Success Response (201)
- **Success** (string) - Indicates the bulk data was uploaded successfully.

#### Response Example
```json
{
  "message": "Bulk data uploaded successfully"
}
```

#### Error Response
- **400 Bad Request**: The XML file is in an invalid format.
- **403 Forbidden**: Requires an appropriate upload access token.
```
Tokens:
Raw