# Readings API

Source: https://help.zira.us/developers/api-reference/readings-api
Summary: Reference the template, query, and ingestion endpoints used for meter-reading integrations.
Updated: 2026-03-26

This section covers the reading template, query, and ingestion endpoints.

## `GET /reading/template`

Purpose:

- return a template or schema helper for building valid reading payloads

## `GET /reading`

Purpose:

- fetch meter readings with time-range filters

Important query options:

- `meterId`
- `startTime`, `endTime`
- or `startHour`, `endHour`, `startOffset`, `endOffset`
- `limit`
- `lastValue`
- `sortDesc`

Validation behavior:

- one valid time-filter mode is required
- `limit` must stay within the supported range

## `POST /reading`

Purpose:

- post readings using metric ID keys inside a values map

Typical request shape:

```json
[
  {
    "meterId": "871",
    "readings": [
      {
        "timestamp": "2026-01-01T10:00:00Z",
        "values": {
          "501": 12.4,
          "502": 55
        }
      }
    ]
  }
]
```

Implementation notes:

- validates meter access
- normalizes values to the meter schema order
- can append submission metadata for certain meter applying types

## `POST /reading/named/`

Purpose:

- legacy compatibility endpoint where metrics are sent by display name

Important behavior:

- maps display-name keys into schema order
- fails if unknown keys remain after normalization

## `POST /reading/ids/`

Purpose:

- post readings as explicit `{ metricId, value }` objects

## `POST /reading/v2/ids/`

Purpose:

- compatibility route using the same request model as `/reading/ids/`

## Integration cautions

- reading endpoints use strict validation
- malformed time ranges or unknown metric mappings can fail fast
- treat ingestion endpoints as validated integration contracts, not loosely typed sinks