> ## Documentation Index > Fetch the complete documentation index at: https://docs.kapa.energy/llms.txt > Use this file to discover all available pages before exploring further. # Get latest telemetry > The most recent measurement Kapa has received for this battery. `point` is null if no measurement has been received yet. ## OpenAPI ````yaml /openapi.yaml get /bat/v1/{id}/telemetry/latest openapi: 3.1.0 info: title: Kapa Energy Battery API version: 1.0.0-draft.1 summary: One API to control and monitor residential batteries across manufacturers. description: > The Kapa Energy Battery API gives HEMS and VPP operators a single interface to send commands to residential batteries and read their telemetry, whatever the manufacturer. Kapa translates each request into the manufacturer's own cloud API. ## Conventions ### Time - Timestamps are RFC 3339, in UTC, with a `Z` suffix: `2026-11-12T18:00:00Z`. - Durations are ISO 8601: `PT15M`. - Time windows are half-open, `[start, end)`: `start` is included, `end` is excluded. ### Power Power is in watts (W), as integers. - **Positive (+)**: the battery is discharging, or the site is exporting to the grid. - **Negative (−)**: the battery is charging, or the site is importing from the grid. Nominal ratings such as `nominal_charge_power_w` are magnitudes and are always positive. ### Energy Energy is in watt-hours (Wh), as integers. Battery levels are expressed as stored energy in Wh rather than state of charge in %, because the meaning of SoC differs between manufacturers. Stored energy is measured against the usable capacity: it ranges from 0 to `usable_capacity_wh`. ### Telemetry - Each data point carries two times: `measured_at`, when the device took the measurement, and `received_at`, when Kapa retrieved it from the manufacturer's cloud. - Data points are never interpolated or resampled. Each point is an actual measurement reported by the manufacturer. Units, signs and field names are standardised across manufacturers; a field the manufacturer does not report is `null`. ## Commands - Commands are asynchronous. Command endpoints return `202 Accepted` with a command whose `status` then evolves. Follow it with `GET /bat/v1/{id}/commands` or the `command.status_changed` webhook. - A `start` in the past is treated as the time Kapa accepts the command. - **Overlaps:** when a new command overlaps existing commands on the same battery, the newest command takes precedence over the overlapping period. Older commands stay in effect outside it. A command whose whole window is covered by newer commands becomes `superseded`. - Outside any command window, the battery follows its **default behaviour**: the mode its owner configured in the manufacturer's app. ## Idempotency Command and batch endpoints accept an optional `Idempotency-Key` header. Kapa stores the key with the response for 24 hours. A retry with the same key and the same body returns the original response without sending anything again. ## Errors Errors use RFC 9457 Problem Details (`application/problem+json`). The `code` field is stable and meant for programs; `title` and `detail` are meant for humans. | `code` | HTTP | Meaning | |---|---|---| | `invalid_parameters` | 400 | A parameter is missing, malformed or inconsistent (e.g. `min_wh` greater than `max_wh`). | | `invalid_time_window` | 400 | `start` is not before `end`, or `end` is in the past. | | `overlapping_operations` | 400 | Two operations of a batch target the same battery over overlapping windows. | | `unauthorized` | 401 | The access token is missing, invalid or expired. | | `battery_not_found` | 404 | No battery with this id is accessible to the client. | | `idempotency_key_in_use` | 409 | A request with the same `Idempotency-Key` is still being processed. | | `action_not_supported` | 422 | The battery cannot apply this command or parameter (e.g. `allow_import: false`). | | `energy_out_of_range` | 422 | An energy level exceeds the battery's usable capacity. | | `idempotency_key_reused` | 422 | The `Idempotency-Key` was already used with a different request body. | ## Webhooks Kapa pushes telemetry and command status changes to an HTTPS endpoint. Delivery is at least once and not ordered: deduplicate with `event_id`, and order data with `measured_at` or `updated_at`. Webhook registration is not covered by this version of the API. servers: - url: https://api.kapa.energy description: Production security: - oauth2: [] tags: - name: Authentication description: Obtain an OAuth 2.0 access token. - name: Batteries description: Static information about a battery. - name: Commands description: Control a single battery and follow the status of its commands. - name: Batches description: Send commands to many batteries in one request. - name: Telemetry description: Read measurements, standardised across manufacturers. paths: /bat/v1/{id}/telemetry/latest: parameters: - $ref: '#/components/parameters/BatteryId' get: tags: - Telemetry summary: Get latest telemetry description: > The most recent measurement Kapa has received for this battery. `point` is null if no measurement has been received yet. operationId: getLatestTelemetry responses: '200': description: Latest telemetry point. content: application/json: schema: $ref: '#/components/schemas/TelemetryLatest' example: battery_id: bat_1 point: measured_at: '2026-11-12T18:10:14Z' received_at: '2026-11-12T18:12:44Z' stored_energy_wh: 7867 battery_power_w: 3150 grid_power_w: 1820 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: parameters: BatteryId: name: id in: path required: true description: Battery identifier. schema: type: string example: bat_1 schemas: TelemetryLatest: type: object required: - battery_id - point properties: battery_id: type: string description: Battery identifier. point: description: Most recent measurement. Null if none has been received yet. oneOf: - $ref: '#/components/schemas/TelemetryPoint' - type: 'null' TelemetryPoint: type: object required: - measured_at - received_at - stored_energy_wh - battery_power_w - grid_power_w properties: measured_at: $ref: '#/components/schemas/Timestamp' description: >- When the device took the measurement, as reported by the manufacturer. received_at: $ref: '#/components/schemas/Timestamp' description: When Kapa retrieved the measurement from the manufacturer's cloud. stored_energy_wh: type: - integer - 'null' minimum: 0 description: > Energy stored in the battery, in Wh, measured against the usable capacity (from 0 to `usable_capacity_wh`). battery_power_w: type: - integer - 'null' description: > Battery power, in W. Positive when discharging, negative when charging. Measured on the side given by `power_measurement_side`. grid_power_w: type: - integer - 'null' description: > Power at the site's grid connection, in W. Positive when exporting, negative when importing. Null if not reported, e.g. when the installation has no grid meter visible to the manufacturer. Problem: type: object description: Error details, following RFC 9457 (Problem Details for HTTP APIs). required: - type - title - status - code properties: type: type: string format: uri-reference description: URI identifying the problem type. title: type: string description: Short, human-readable summary of the problem type. status: type: integer description: HTTP status code. code: type: string description: >- Stable, machine-readable error code. See Errors in the API description. detail: type: string description: Human-readable explanation specific to this occurrence. invalid_params: type: array description: Parameters that caused the error, if any. items: type: object required: - name - reason properties: name: type: string reason: type: string Timestamp: type: string format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$ description: RFC 3339 timestamp in UTC, with a `Z` suffix. examples: - '2026-11-12T18:00:00Z' responses: Unauthorized: description: The access token is missing, invalid or expired. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://api.kapa.energy/problems/unauthorized title: Unauthorized status: 401 code: unauthorized detail: The access token has expired. NotFound: description: No battery with this id is accessible to the client. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://api.kapa.energy/problems/battery-not-found title: Battery not found status: 404 code: battery_not_found detail: No battery with id bat_9 is accessible to this client. securitySchemes: oauth2: type: oauth2 description: OAuth 2.0 client credentials. Obtain a token from `POST /token`. flows: clientCredentials: tokenUrl: https://api.kapa.energy/token scopes: {} ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.