Explainer API Reference

The Device Explainers API exposes the same operations for heat pumps and solar inverters. All endpoints use the following base URL and require a bearer token:

https://app.podero.com/api/partners/v2.0

Endpoints

Heat pump
Solar inverter

Method	Endpoint	Description
`GET`	`/org/{org_id}/users/{user_id}/heat-pumps/{heat_pump_id}/explainer/current`	Get the explanation for the active plan
`GET`	`/org/{org_id}/users/{user_id}/heat-pumps/{heat_pump_id}/explainer/historical`	Get the explanation for a completed window
`POST`	`/org/{org_id}/users/{user_id}/heat-pumps/{heat_pump_id}/explainer/{explainer_id}/feedback`	Rate an explanation
`POST`	`/org/{org_id}/users/{user_id}/heat-pumps/{heat_pump_id}/explainer/{explainer_id}/dismiss`	Dismiss an explanation

Method	Endpoint	Description
`GET`	`/org/{org_id}/users/{user_id}/inverters/{inverter_id}/explainer/current`	Get the explanation for the active plan
`GET`	`/org/{org_id}/users/{user_id}/inverters/{inverter_id}/explainer/historical`	Get the explanation for a completed window
`POST`	`/org/{org_id}/users/{user_id}/inverters/{inverter_id}/explainer/{explainer_id}/feedback`	Rate an explanation
`POST`	`/org/{org_id}/users/{user_id}/inverters/{inverter_id}/explainer/{explainer_id}/dismiss`	Dismiss an explanation

Path parameters

string (UUID)

required

Organization that owns the user and device.

string (UUID)

required

Owner of the device. This can differ from the authenticated caller when an organization administrator accesses a member’s device.

string (UUID)

Heat pump to explain. Required on heat-pump endpoints.

string (UUID)

Solar inverter to explain. Required on inverter endpoints.

string (UUID)

Durable identifier returned by an explainer read. Required for feedback and dismissal.

Get the current explainer

Returns a customer-facing explanation of the device’s active optimization plan.

Query parameters

string

Optional language code, such as en or de. When omitted, Podero uses the organization’s default language.

Response

{
  "id": "c92b58d6-14a7-4eba-9836-cef076735a4a",
  "explanation": "Podero will shift energy use toward the lower-price hours this afternoon.",
  "feedback": null
}

The request returns 200 OK with JSON null when there is no current explanation, such as when an optimization plan has not been solved. The first request for a plan can take several seconds because it generates and caches the explanation synchronously.

Get a historical explainer

Returns a customer-facing explanation of a completed past window.

Query parameters

string (date-time)

required

Inclusive start of the window as an ISO 8601 timestamp.

string (date-time)

required

End of the window as an ISO 8601 timestamp. Request completed past windows only.

string

Optional language code, such as en or de. When omitted, Podero uses the organization’s default language.

The response uses the same schema as the current endpoint. An unavailable or future window returns 200 OK with JSON null.

Explainer response schema

string (UUID)

required

Durable explainer identifier used by feedback and dismissal requests.

string

required

Customer-facing narrative in the resolved language. Render this value as plain text.

object | null

required

The authenticated caller’s latest rating, or null when that caller has not rated the explainer.

Show feedback properties

boolean

required

Whether the caller found the explanation helpful.

string | null

required

Negative-feedback reason: wrong_language, confusing, or disagree_with_steering. This is null for positive feedback or when no reason was supplied.

Submit feedback

Records a rating for the authenticated caller. The caller is the actor associated with the feedback even when user_id identifies another member whose device is being accessed.

Request body

boolean

required

Whether the explanation was helpful.

string

Optional negative-feedback reason. Accepted values are wrong_language, confusing, and disagree_with_steering. Omit this field for positive feedback.

{
  "helpful": false,
  "reason": "confusing"
}

Response

{ "recorded": true }

An unsupported reason returns 422 Unprocessable Entity.

Dismiss an explainer

Dismisses the explainer identified by explainer_id. The request has no body.

Response

{ "dismissed": true }

A dismissed explainer is not returned by subsequent explainer reads.

Status codes

Status	Meaning
`200 OK`	The read or action succeeded. Explainer reads can return a JSON body of `null`.
`401 Unauthorized`	The bearer token is missing or invalid.
`403 Forbidden`	The authenticated caller cannot access the requested organization resource.
`404 Not Found`	The user or device does not exist in the specified organization, or the explainer cannot be addressed.
`422 Unprocessable Entity`	A required value is missing, malformed, or outside the accepted enum values.

Implementation guide

See client-side gating, caching, loading, feedback, and dismissal recommendations.

Overview

Getting Started

End-User Workflows

Back-Office Workflows

Notifications

Explainers

API Reference

Heat Pumps

Electric Vehicles

Solar Inverters

Endpoints

Path parameters

Get the current explainer

Query parameters

Response

Get a historical explainer

Query parameters

Explainer response schema

Submit feedback

Request body

Response

Dismiss an explainer

Response

Status codes

Implementation guide

​Endpoints

​Path parameters

​Get the current explainer

​Query parameters

​Response

​Get a historical explainer

​Query parameters

​Explainer response schema

​Submit feedback

​Request body

​Response

​Dismiss an explainer

​Response

​Status codes

Implementation guide

Endpoints

Path parameters

Get the current explainer

Query parameters

Response

Get a historical explainer

Query parameters

Explainer response schema

Submit feedback

Request body

Response

Dismiss an explainer

Response

Status codes