Device endpoints

The Device APIs provide a read-only view of devices owned by 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 Device APIs in this order:

1. Call GET /openapi/devices to discover accessible devices and their capabilities.
2. Store the returned device_id as the stable identifier for subsequent calls.
3. Use realtime_supported and history_supported to determine whether realtime or history data is available for each device before requesting that data.
4. Read current operating data from the Realtime endpoint and energy trends from the History endpoint.

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

Endpoint overview

Endpoint	Purpose	Main input
GET /openapi/devices	Discover devices in the token organization	Optional page and rows query parameters
GET /openapi/devices/{device_id}/realtime	Read the latest supported metrics for one device	device_id path parameter
GET /openapi/devices/{device_id}/history	Read UTC-bucketed energy series for one device	device_id, time range, and interval

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 devices

Returns a paginated list of devices directly available to the organization.

Method and endpoint

GET /openapi/devices

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 20; 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:

• device_id, the identifier to use with Device endpoints.
• name and model, where model is the user-facing model display name.
• serial_number and product_type for identification and classification.
• status, representing the latest known connectivity state.
• realtime_supported and history_supported, which indicate whether realtime and history data are available for the device.

The list intentionally does not expose firmware information or Site membership. Treat the capability flags as authoritative rather than maintaining your own model allowlist.

Realtime metrics

Returns the latest normalized operating metrics supported by a device.

Method and endpoint

GET /openapi/devices/{device_id}/realtime

URL parameters

Name	Location	Required	Type	Description
device_id	Path	Yes	String	Device identifier returned by GET /openapi/devices.

Request body

None. This endpoint does not accept a request body.

Response

The response has a common outer shape:

• device_id, model, and product_type identify the device and metric family.
• observed_at is the UTC collection time when a reliable timestamp is available.
• is_stale indicates that the latest reading is older than the freshness window or has no reliable observation time.
• metrics contains the product-specific measurements.

Product-specific metric shapes

The metrics object is intentionally different for each supported product_type. Use product_type as the discriminator when decoding the response:

Product type	Metric focus
storage	PV, battery, grid and load power; battery state of charge; normalized voltage and current measurements
gateway	Phase A, B and C voltage, current and active power

Every field defined for the selected product type is present. A value of null means Mango Power does not have a trustworthy value for that measurement; it does not mean zero. Ignore unknown fields when using a forward-compatible decoder.

The exact metric names, units, nullability, and product-specific schemas are maintained in the API reference.

Energy history

Returns energy totals as a set of time series. It is intended for reporting and trend analysis rather than reconstructing instantaneous power.

Method and endpoint

GET /openapi/devices/{device_id}/history

URL parameters

Name	Location	Required	Type	Description
device_id	Path	Yes	String	Device identifier returned by GET /openapi/devices.
start_at	Query	Yes	Date-time	Inclusive UTC range start in ISO 8601 format.
end_at	Query	Yes	Date-time	Exclusive UTC range end in ISO 8601 format.
interval	Query	Yes	String	UTC bucket size: 1h, 1d, or 1mo.

Range boundaries must align to the requested UTC bucket: hourly ranges start on an hour, daily ranges at 00:00 UTC, and monthly ranges on the first day of a month at 00:00 UTC. Maximum ranges are 31 days for 1h, 2 years for 1d, and 10 years for 1mo.

Request body

None. This endpoint does not accept a request body.

Response

The response reports timezone: UTC and returns separate series entries for PV energy, battery charge and discharge, grid import and export, load consumption, and AC-coupled energy. Each series uses kWh, sum aggregation, and timestamped bucket values.

Missing or untrusted buckets are omitted from points; a measured value of zero remains 0. Your integration should therefore join points by timestamp instead of assuming every series has an identical number of entries.

Capability and access behavior

Check capability flags before calling a data endpoint. A device may appear in the list while not supporting Realtime, History, or both.

If a device_id does not exist in the token organization, the API returns the same not-found response whether the device 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.