Site endpoints

The Site APIs provide a read-only view of sites available to the organization associated with your Application Client. You do not send an organization ID: Mango Power derives the organization from the Bearer token and applies that boundary to every request.

Typical integration flow

Most integrations use the Site APIs in this order:

1. Call GET /openapi/sites to discover accessible sites and their organization metadata.
2. Store the returned site_id as the stable identifier for subsequent calls.
3. Use GET /openapi/sites/{site_id}/devices when you need the devices currently bound to a site.
4. Read the current site power-flow snapshot from the Realtime endpoint and energy trends from the Energy History endpoint.

All four endpoints require an openapi.read Bearer token. See Authentication for the token flow.

Endpoint overview

Endpoint	Purpose	Main input
GET /openapi/sites	Discover sites available to the token organization	Optional page and rows query parameters
GET /openapi/sites/{site_id}/devices	List devices currently bound to one site	site_id path parameter, optional page and rows
GET /openapi/sites/{site_id}/realtime	Read the latest normalized site power-flow metrics	site_id path parameter
GET /openapi/sites/{site_id}/energy/history	Read fixed 1-hour site energy series	site_id, start_at, and end_at

The API reference contains the authoritative schemas, constraints, and endpoint-specific HTTP responses. The sections below explain how the endpoints fit together and how to interpret their data.

List sites

Returns a paginated list of sites available to the organization associated with the access token. The list can include sites from child organizations, so each item includes org_name.

Method and endpoint

GET /openapi/sites

URL parameters

Name	Location	Required	Type	Description
page	Query	No	Integer	Page number. Defaults to 1.
rows	Query	No	Integer	Items per page. Defaults to 100; maximum 1000.

Request body

None. This endpoint does not accept a request body.

Response

The response contains items for the requested page and total for the complete matching set.

Each item provides:

• site_id, the identifier to use with Site endpoints.
• org_name, the name of the organization that owns the site.
• name and timezone, the site’s display name and stored UTC offset when available.
• created_by, the account identifier that created the site when available.
• device_count, the number of devices currently associated with the site.

Sites are returned in a stable order. An organization with no accessible sites receives an empty items array and total: 0.

List site devices

Returns the devices currently bound to a site. The device item shape and capability fields are the same as GET /openapi/devices; use realtime_supported and history_supported before requesting device data.

Method and endpoint

GET /openapi/sites/{site_id}/devices

URL parameters

Name	Location	Required	Type	Description
site_id	Path	Yes	UUID string	Site identifier returned by GET /openapi/sites.
page	Query	No	Integer	Page number. Defaults to 1.
rows	Query	No	Integer	Items per page. Defaults to 100; maximum 1000.

Request body

None. This endpoint does not accept a request body.

Response

The response contains items and total. A site with no bound devices returns items: [] and total: 0.

The endpoint returns devices bound to the requested site so that the device list remains aligned with site-level energy data. A device_id may therefore appear here even when it is not included in a separate organization-device list.

Realtime metrics

Returns the latest normalized power-flow snapshot for a site.

Method and endpoint

GET /openapi/sites/{site_id}/realtime

URL parameters

Name	Location	Required	Type	Description
site_id	Path	Yes	UUID string	Site identifier returned by GET /openapi/sites.

Request body

None. This endpoint does not accept a request body.

Response

The response has a common outer shape:

• site_id identifies the site.
• observed_at is the UTC collection time when a reliable timestamp is available.
• is_stale indicates that the snapshot is older than the freshness window or has no reliable observation time.
• metrics contains pv_power, load_power, grid_power, battery_power, and ac_couple_power, all in watts (W).

When a snapshot is stale or unavailable, the five metric values are null. A real measured zero remains 0; do not use zero to represent missing data.

Energy history

Returns site energy-flow totals as time series for reporting and trend analysis. This endpoint always uses UTC 1-hour buckets; it does not accept an interval parameter.

Method and endpoint

GET /openapi/sites/{site_id}/energy/history

URL parameters

Name	Location	Required	Type	Description
site_id	Path	Yes	UUID string	Site identifier returned by GET /openapi/sites.
start_at	Query	Yes	Date-time	Inclusive UTC range start in ISO 8601 format, aligned to an hour.
end_at	Query	Yes	Date-time	Exclusive UTC range end in ISO 8601 format, aligned to an hour.

The requested range may not exceed three calendar months. The total range must be positive, and both boundaries must align to UTC hour boundaries.

Request body

None. This endpoint does not accept a request body.

Response

The response reports timezone: UTC, interval: 1h, and seven separate series entries:

• PV energy (energy_pv)
• Battery charge and discharge (energy_battery_charge, energy_battery_discharge)
• Grid import and export (energy_grid_import, energy_grid_export)
• Load consumption (energy_load)
• AC-coupled energy (energy_ac_couple)

Every series uses kWh and sum aggregation. Missing or untrusted buckets are omitted from points; a measured value of zero remains 0. Join points by timestamp instead of assuming every series has an identical number of entries.

Capability and access behavior

Use a site_id returned by GET /openapi/sites. A malformed site identifier or invalid query parameter returns HTTP 400. If a site does not exist in the token organization, the API returns the same HTTP 422 business error whether the site is unknown or belongs to another organization. This prevents integrations from discovering resources outside their authorization boundary.

For exact status codes and response bodies, use the API reference. Registered business errors return HTTP 422 with a stable numeric code. See Error handling for the complete decision flow and Business Codes list.