BEN MyMeter API

Online Metering Data Collection Platform — machine/IoT API. Authentication: every request carries `Authorization: Bearer <token>`. Tokens are created in *Settings → API tokens*, are bound to exactly one tenant, and carry scopes. Reporting requires the `data:report` scope; the read/query endpoints require `data:read`. Rate limits: 60 requests/minute per token. Responses include `X-RateLimit-Limit` / `X-RateLimit-Remaining`.

Reports one or many readings for meters of the token's tenant. - Meter identifiers unknown to the tenant are **auto-provisioned** (filed under "Ungrouped meters"). Auto-provisioning is bounded per tenant (default 100 new meters/hour); beyond the cap, items for NEW identifiers return `status: rejected_provision_limit` while readings for existing meters are unaffected. - On the hosted service a **plan meter limit** applies as well. At the limit, items for NEW identifiers return `status: rejected_plan_limit` and the workspace owner needs to upgrade. Readings for meters that ALREADY EXIST are never refused for a plan or payment reason — meter history cannot be reconstructed once a device has moved on, so the commercial lever is access to the data, never acceptance of it. - **Idempotent:** a reading is identified by `(meter, kind, recorded_at)`; retries of the same report are answered with `status: duplicate` and never double-count. - **Model-aware:** every item is validated against the meter's assigned device profile (see `profile` on `/meters`). Meters on the *generic* profile report the plain `kind`/`value`/`unit` shape; meters assigned another model report a `payload` object matching that profile's schema (e.g. the IZAR register reading plus status flags). The payload is normalized into canonical readings; the raw payload is retained on the stored reading for traceability. - **Pulse counters** (#44) report `pulses` (absolute counter) and/or `pulse_delta` (increment since the last report); the per-meter **pulse weight** ("1 pulse = weight × unit", configured in the meter settings) converts counts into measurements. Items for meters without that configuration are answered per item with `status: rejected_unconfigured` — the meter itself IS provisioned, so it can be configured and the next report ingests. Multi-channel pulse devices report each channel as its own meter identifier. - The optional `profile` field declares the device's model explicitly: an unknown meter is then auto-provisioned directly onto that profile (nothing left to review), and a meter still on the unconfirmed provisioning default is upgraded to the declared model. A declaration that contradicts a *user-confirmed* profile assignment is rejected — reassign the meter in settings first. - **Atomic validation:** the whole batch is validated before anything is stored. Any schema violation rejects the entire request with a 422 naming the offending field (e.g. `readings.3.payload.value`); nothing is written.

{
    "readings": [
        {
            "meter": "MTR-00012345",
            "kind": "consumption",
            "value": 1.25,
            "unit": "kwh",
            "recorded_at": "2026-08-15T10:00:00Z"
        }
    ]
}

{
    "readings": [
        {
            "meter": "MTR-00012345",
            "kind": "saldo",
            "value": 4521.75,
            "unit": "kwh",
            "recorded_at": "2026-08-15T10:00:00Z"
        }
    ]
}

{
    "readings": [
        {
            "meter": "IZAR-88231",
            "profile": "izar",
            "unit": "m3",
            "payload": {
                "value": 4521.5,
                "status": [
                    "leakage",
                    "battery_low"
                ]
            },
            "recorded_at": "2026-08-15T10:00:00Z"
        }
    ]
}

{
    "readings": [
        {
            "meter": "PULSE-7",
            "profile": "pulse_counter",
            "payload": {
                "pulses": 12845
            },
            "recorded_at": "2026-08-15T10:00:00Z"
        }
    ]
}

Meter inventory of the token's tenant, ordered by identifier. Requires the `data:read` scope. Use the returned `id` values to filter `/readings`.

Readings of the token's tenant within a time range, optionally filtered to one meter or one group subtree and/or one kind. Requires the `data:read` scope. - Defaults: `to` = now, `from` = `to` − 7 days; the range is capped at 366 days. - `aggregate=raw` returns individual readings (oldest first), including canonical values and quality flags (#29). - `aggregate=hourly|daily` returns one bucket per (bucket, meter, kind) with `sum`, `min`, `max`, `avg` and `reading_count`, computed over CANONICAL values (kwh / m3, #29) — readings without a canonical value (unit mismatch, not yet backfilled) are excluded from buckets. For `consumption` the meaningful figure is usually `sum`; for `saldo` (a counter state) use `min`/`max`/`avg` — summing counter states is meaningless. - `tz=<IANA zone>` buckets in local wall time — daily buckets on DST-change days correctly span 23/25 hours; `bucket_start` is then local time. Raw rows gain `recorded_at_local`. Storage and defaults stay UTC. - `derive=consumption` (requires `meter_id`, no `aggregate`) returns the consumption series derived from consecutive SALDO readings, bridging counter rollovers and recorded meter exchanges (#29). Intervals longer than the meter's expected cadence are marked `gap: true`; `interpolate=linear` (opt-in) splits such deltas into cadence slots, each marked `interpolated: true`. Unknown intervals (exchange without baselines, unexplained decrease) have `consumption: null` — values are never invented.

Device-status reports of the token's tenant, newest first. Requires the `data:read` scope. Each row is one status the device itself reported (#45): the provider's raw flags verbatim plus the normalized canonical codes every profile maps onto. An empty `statuses` list means the device reported all-clear — a leak appearing and later clearing is therefore two traceable rows. Device status is distinct from the platform-computed data-quality flags on `/readings` (#29); both surface as metering issues in the UI.