> ## Documentation Index
> Fetch the complete documentation index at: https://developers.podero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Explainer API Reference

> Endpoints, parameters, and schemas for heat-pump and solar-inverter explainers

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:

```text theme={null}
https://app.podero.com/api/partners/v2.0
```

## Endpoints

<Tabs>
  <Tab title="Heat pump">
    | 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                     |
  </Tab>

  <Tab title="Solar inverter">
    | 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                     |
  </Tab>
</Tabs>

## Path parameters

<ParamField path="org_id" type="string (UUID)" required>
  Organization that owns the user and device.
</ParamField>

<ParamField path="user_id" type="string (UUID)" required>
  Owner of the device. This can differ from the authenticated caller when an organization administrator accesses a member's device.
</ParamField>

<ParamField path="heat_pump_id" type="string (UUID)">
  Heat pump to explain. Required on heat-pump endpoints.
</ParamField>

<ParamField path="inverter_id" type="string (UUID)">
  Solar inverter to explain. Required on inverter endpoints.
</ParamField>

<ParamField path="explainer_id" type="string (UUID)">
  Durable identifier returned by an explainer read. Required for feedback and dismissal.
</ParamField>

## Get the current explainer

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

### Query parameters

<ParamField query="language" type="string">
  Optional language code, such as `en` or `de`. When omitted, Podero uses the organization's default language.
</ParamField>

### Response

```json theme={null}
{
  "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

<ParamField query="start" type="string (date-time)" required>
  Inclusive start of the window as an ISO 8601 timestamp.
</ParamField>

<ParamField query="end" type="string (date-time)" required>
  End of the window as an ISO 8601 timestamp. Request completed past windows only.
</ParamField>

<ParamField query="language" type="string">
  Optional language code, such as `en` or `de`. When omitted, Podero uses the organization's default language.
</ParamField>

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

## Explainer response schema

<ResponseField name="id" type="string (UUID)" required>
  Durable explainer identifier used by feedback and dismissal requests.
</ResponseField>

<ResponseField name="explanation" type="string" required>
  Customer-facing narrative in the resolved language. Render this value as plain text.
</ResponseField>

<ResponseField name="feedback" type="object | null" required>
  The authenticated caller's latest rating, or `null` when that caller has not rated the explainer.

  <Expandable title="feedback properties">
    <ResponseField name="helpful" type="boolean" required>
      Whether the caller found the explanation helpful.
    </ResponseField>

    <ResponseField name="reason" type="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.
    </ResponseField>
  </Expandable>
</ResponseField>

## 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

<ParamField body="helpful" type="boolean" required>
  Whether the explanation was helpful.
</ParamField>

<ParamField body="reason" type="string">
  Optional negative-feedback reason. Accepted values are `wrong_language`, `confusing`, and `disagree_with_steering`. Omit this field for positive feedback.
</ParamField>

```json theme={null}
{
  "helpful": false,
  "reason": "confusing"
}
```

### Response

```json theme={null}
{ "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

```json theme={null}
{ "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.                           |

<Card title="Implementation guide" icon="code" href="/partner-api/explainers/integration">
  See client-side gating, caching, loading, feedback, and dismissal recommendations.
</Card>