Device Explainers

Explainers turn a device’s optimization plan into a short, customer-facing narrative. The API supports current and historical explainers for heat pumps and solar inverters, together with feedback and dismissal actions. An explainer is generated on the first read of a plan or historical window and then cached. Because the first request can take several seconds, show a loading state and do not use an aggressive request timeout.

Only request an explainer when the device is actively using smart optimization and explainers are enabled for the organization. For solar inverters, also confirm that a battery is connected. This is the same fail-closed approach used by myPodero.

Supported devices and endpoints

Substitute heat-pumps/{heat_pump_id} or inverters/{inverter_id} for {device_path} in the endpoints below.

Purpose	Method	Endpoint
Explain the active plan	`GET`	`/org/{org_id}/users/{user_id}/{device_path}/explainer/current`
Explain a completed window	`GET`	`/org/{org_id}/users/{user_id}/{device_path}/explainer/historical`
Record feedback	`POST`	`/org/{org_id}/users/{user_id}/{device_path}/explainer/{explainer_id}/feedback`
Dismiss an explainer	`POST`	`/org/{org_id}/users/{user_id}/{device_path}/explainer/{explainer_id}/dismiss`

All examples use the base URL https://app.podero.com/api/partners/v2.0 and require a bearer token. The user_id in the path is the owner of the device.

1. Fetch the current explainer

Use the current endpoint for the active optimization plan. You can pass an optional language query parameter, such as en or de. When it is omitted, Podero uses the organization’s default language.

Heat pump
Solar inverter

curl -G \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/heat-pumps/{heat_pump_id}/explainer/current' \
  -H 'Authorization: Bearer {auth_token}' \
  --data-urlencode 'language=de'

const params = new URLSearchParams({ language: currentLanguage });
const response = await fetch(
  `${baseUrl}/org/${orgId}/users/${userId}/heat-pumps/${heatPumpId}/explainer/current?${params}`,
  { headers: { Authorization: `Bearer ${authToken}` } },
);

if (!response.ok) throw new Error(`Explainer request failed: ${response.status}`);
const explainer: Explainer | null = await response.json();

curl -G \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/inverters/{inverter_id}/explainer/current' \
  -H 'Authorization: Bearer {auth_token}' \
  --data-urlencode 'language=de'

const params = new URLSearchParams({ language: currentLanguage });
const response = await fetch(
  `${baseUrl}/org/${orgId}/users/${userId}/inverters/${inverterId}/explainer/current?${params}`,
  { headers: { Authorization: `Bearer ${authToken}` } },
);

if (!response.ok) throw new Error(`Explainer request failed: ${response.status}`);
const explainer: Explainer | null = await response.json();

A successful response contains a durable id, the localized explanation, and the authenticated caller’s own most recent feedback:

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

The response can be 200 OK with a JSON body of null when no explanation is available, for example when a plan has not been solved yet. Treat this as a normal empty state rather than an error.

Include the selected language in your client cache key. When a customer changes language, fetch again instead of displaying text cached in the previous language. myPodero keeps current explainers fresh for five minutes.

2. Fetch a historical explainer

Use the historical endpoint to explain what happened during a completed past window. Supply start and end as ISO 8601 timestamps. Use URL encoding rather than concatenating the query string so that timezone offsets containing + are preserved.

Heat pump
Solar inverter

curl -G \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/heat-pumps/{heat_pump_id}/explainer/historical' \
  -H 'Authorization: Bearer {auth_token}' \
  --data-urlencode 'start=2026-09-16T00:00:00Z' \
  --data-urlencode 'end=2026-09-17T00:00:00Z' \
  --data-urlencode 'language=de'

const params = new URLSearchParams({
  start: '2026-09-16T00:00:00Z',
  end: '2026-09-17T00:00:00Z',
  language: currentLanguage,
});

const response = await fetch(
  `${baseUrl}/org/${orgId}/users/${userId}/heat-pumps/${heatPumpId}/explainer/historical?${params}`,
  { headers: { Authorization: `Bearer ${authToken}` } },
);

if (!response.ok) throw new Error(`Explainer request failed: ${response.status}`);
const explainer: Explainer | null = await response.json();

curl -G \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/inverters/{inverter_id}/explainer/historical' \
  -H 'Authorization: Bearer {auth_token}' \
  --data-urlencode 'start=2026-09-16T00:00:00Z' \
  --data-urlencode 'end=2026-09-17T00:00:00Z' \
  --data-urlencode 'language=de'

const params = new URLSearchParams({
  start: '2026-09-16T00:00:00Z',
  end: '2026-09-17T00:00:00Z',
  language: currentLanguage,
});

const response = await fetch(
  `${baseUrl}/org/${orgId}/users/${userId}/inverters/${inverterId}/explainer/historical?${params}`,
  { headers: { Authorization: `Bearer ${authToken}` } },
);

if (!response.ok) throw new Error(`Explainer request failed: ${response.status}`);
const explainer: Explainer | null = await response.json();

Request completed windows only. A future or otherwise unavailable window returns 200 OK with null. For daily history views, normalize the selected day to explicit UTC instants and use the same window in the cache key. Historical explainers are persisted for their window. myPodero therefore caches a successfully fetched historical explainer for the rest of the session.

3. Collect feedback

Use the explainer id from either read endpoint when a customer rates the explanation. Positive feedback only needs helpful. Negative feedback can include one of these stable reason codes:

wrong_language
confusing
disagree_with_steering

Send the code, never a translated label.

Heat pump
Solar inverter

curl -X POST \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/heat-pumps/{heat_pump_id}/explainer/{explainer_id}/feedback' \
  -H 'Authorization: Bearer {auth_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "helpful": false,
    "reason": "confusing"
  }'

const body = { helpful: false, reason: 'confusing' };

await fetch(
  `${baseUrl}/org/${orgId}/users/${userId}/heat-pumps/${heatPumpId}/explainer/${explainerId}/feedback`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${authToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  },
);

curl -X POST \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/inverters/{inverter_id}/explainer/{explainer_id}/feedback' \
  -H 'Authorization: Bearer {auth_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "helpful": false,
    "reason": "confusing"
  }'

const body = { helpful: false, reason: 'confusing' };

await fetch(
  `${baseUrl}/org/${orgId}/users/${userId}/inverters/${inverterId}/explainer/${explainerId}/feedback`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${authToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  },
);

The response is:

{ "recorded": true }

Feedback belongs to the authenticated caller, not necessarily the device owner named by user_id. The next read returns only that caller’s latest rating in the feedback field. An unsupported reason code returns 422 Unprocessable Entity.

4. Dismiss an explainer

Dismiss an explainer when the customer closes it permanently:

Heat pump
Solar inverter

curl -X POST \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/heat-pumps/{heat_pump_id}/explainer/{explainer_id}/dismiss' \
  -H 'Authorization: Bearer {auth_token}'

curl -X POST \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/inverters/{inverter_id}/explainer/{explainer_id}/dismiss' \
  -H 'Authorization: Bearer {auth_token}'

The response is:

{ "dismissed": true }

Remove the card from local state immediately, then restore it if the request fails. A dismissed explainer is not returned by subsequent reads.

Recommended UI behavior

Check the organization’s explainer setting and the device’s smart-optimization state before making a request.
Show a loading placeholder because the first read may generate the explanation synchronously.
Render nothing when the API returns null.
Display explanation as plain text. Do not interpret it as HTML or Markdown.
Use id for feedback and dismissal actions.
Hide the feedback prompt when feedback is already present, or reflect the saved rating.
Do not retry generation requests automatically in a tight loop. myPodero disables automatic retries and lets the user or a later refresh try again.

TypeScript types

type ExplainerFeedback = {
  helpful: boolean;
  reason: 'wrong_language' | 'confusing' | 'disagree_with_steering' | null;
};

type Explainer = {
  id: string;
  explanation: string;
  feedback: ExplainerFeedback | null;
};

The complete endpoint schemas are also available in the interactive API Reference.

Overview

Getting Started

End-User Workflows

Back-Office Workflows

Notifications

Explainers

API Reference

Heat Pumps

Electric Vehicles

Solar Inverters

Supported devices and endpoints

1. Fetch the current explainer

2. Fetch a historical explainer

3. Collect feedback

4. Dismiss an explainer

Recommended UI behavior

TypeScript types

​Supported devices and endpoints

​1. Fetch the current explainer

​2. Fetch a historical explainer

​3. Collect feedback

​4. Dismiss an explainer

​Recommended UI behavior

​TypeScript types

Supported devices and endpoints

1. Fetch the current explainer

2. Fetch a historical explainer

3. Collect feedback

4. Dismiss an explainer

Recommended UI behavior

TypeScript types