Ask about auth, request shape, or code samples in your preferred language.

API Assistant

Every request to public SDK endpoints must include a valid API key header.

This endpoint does not require a request body.

Use this endpoint before posting readings when your integration needs schema guidance for a specific data source or form.

Failures return a JSON body with a `message` and an `internalErrorCode`, at the status shown below. Whenever the underlying error carries structured detail — which every schema-validation failure does — the body is replaced with a generic `Internal server error.` / `02-001` pair while the real status code is kept. Branch on the HTTP status and on `internalErrorCode`; never parse the message text.

x-api-key

Required ID of the data source or form you want the template for.

meterId

CSV text. Line 1 is the header row. Line 2 is the data source’s most recent reading in the same column order, and is present only when it has readings. Split on newlines and parse as CSV — do not try to JSON-parse this value.

data

Returns a CSV document as a single string — not a JSON structure. The first line is the header row: `timestamp` followed by one column per metric you are allowed to write to, in the order the importer expects. When the data source already has at least one reading, a second line holds that reading as a worked example.

Return a template or schema helper for building valid reading payloads for a specific data source.

Download Template


## `GET /reading/template`

Use this endpoint before posting readings when your integration needs schema guidance for a specific data source or form.

## Authentication

```http
x-api-key: <your-api-key>
```

See [API Authentication](/developers/api-reference/api-authentication) for how to create a key.

## Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `meterId` | string | yes | Required ID of the data source or form you want the template for. |

## Response

`200 OK`

Returns a CSV document as a single string — not a JSON structure. The first line is the header row: `timestamp` followed by one column per metric you are allowed to write to, in the order the importer expects. When the data source already has at least one reading, a second line holds that reading as a worked example.

```json
{
  "data": "\"timestamp\",\"Accumulated Volume\",\"Flow Rate\"\n\"2026-01-14T09:15:00.000+02:00\",148.25,7.52"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data` | string | CSV text. Line 1 is the header row. Line 2 is the data source’s most recent reading in the same column order, and is present only when it has readings. Split on newlines and parse as CSV — do not try to JSON-parse this value. |

### Good to know

- This is the column contract for the CSV import flow, not a description of the `POST /reading` JSON body. The columns are metric display names; `POST /reading` is keyed by metric ID instead.
- A data source with no readings yet returns the header row only — one line, no trailing newline. Handle the missing second line.
- Columns cover only the metrics you can write. Anything Zira calculates for you is left out, because supplying it would be ignored.
- The importer matches columns by their header name, not by position, so you can reorder them. Only the `timestamp` column is mandatory. Keeping the headers exactly as returned is still the safest option.
- Leave out the `Submission Id`, `Submitted By` and `Submitted At` columns — the importer ignores them.
- The sample row’s timestamp is in the data source’s own time zone and carries an offset, unlike the UTC timestamps that `GET /reading` returns.
- Typical flow: call this to learn the columns, fill in one row per reading, then call `GET /import` for an upload URL and upload the finished file.

## Errors

Failures return a JSON body with a `message` and an `internalErrorCode`, at the status shown below. Whenever the underlying error carries structured detail — which every schema-validation failure does — the body is replaced with a generic `Internal server error.` / `02-001` pair while the real status code is kept. Branch on the HTTP status and on `internalErrorCode`; never parse the message text.

```json
{
  "message": "Internal server error.",
  "internalErrorCode": "02-001"
}
```

| Status | Meaning |
| --- | --- |
| `400` | The request failed validation — a missing required field, a field the schema does not allow, an unparseable body, a value out of range, or a malformed `lastValue`. |
| `401` | The API key resolved to a user context that is not allowed to read or write the record you asked for. |
| `403` | The `x-api-key` header is missing or is not a recognised key. API Gateway rejects the call before the endpoint runs, so the body is only `{"message":"Forbidden"}`. |
| `409` | The write conflicts with an existing record, or it references a record that does not exist. |
| `429` | The API key exceeded the rate limit or quota on its usage plan. Also returned by API Gateway rather than the endpoint. |
| `500` | Unexpected server error, or the database returned no result where one was required. |



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


Reference the template, query, and ingestion endpoints used for meter-reading integrations.

Readings API


Zira publishes its documentation as an **MCP server**: a small service that an AI assistant can
call as a tool. Once it is connected, the assistant can search the product guides, the API
reference, and the release notes on its own, and answer from the current documentation instead of
from whatever it happens to remember about Zira.

Use it when you are building an integration with an AI coding assistant, or when you want an
assistant to answer product questions accurately.

## What you need

Nothing. The server is public, read-only, and needs no API key.

```text
https://help.zira.us/api/mcp
```

It serves the same documentation as this site, over the Model Context Protocol instead of over web
pages. It holds no customer data and cannot read or change anything in a Zira account.

## Connect it

The exact steps depend on your client, but every client needs the same two things: the transport
(`http`, sometimes called "streamable HTTP" or "remote") and the URL above.

### Claude Code

```bash
claude mcp add --transport http zira-docs https://help.zira.us/api/mcp
```

### Clients configured with a JSON file

Most desktop assistants and editors read a config file. Add one entry:

```json
{
  "mcpServers": {
    "zira-docs": {
      "type": "http",
      "url": "https://help.zira.us/api/mcp"
    }
  }
}
```

Claude Code picks this up in your next session; Claude Desktop reads its config at launch, so restart it.

### Anything else

Point any MCP client at the URL with the HTTP transport. If your client only supports local
`stdio` servers, put a stdio-to-HTTP bridge in front of it — the server itself needs no special
handling.

## Check that it worked

Ask the assistant something that can only be answered from the documentation, and watch for it to
call a tool:

```text
Using the Zira docs, how do I post readings by metric id?
```

A connected client lists three tools:

| Tool | What it does |
|---|---|
| `search_docs` | Searches the documentation and returns ranked matches with a snippet |
| `read_doc` | Returns one article in full, as Markdown |
| `list_docs` | Lists every article, so the assistant can see what exists |

Your client may also offer the articles as attachable **resources**, one per article, if it
supports them.

## What it can search

| Corpus | Contents |
|---|---|
| `guides` | Product guides — how operators, supervisors, and plant managers use Zira |
| `developers` | Developer documentation — authentication, endpoints, request and response shapes |
| `changelog` | Release notes, newest first |

The assistant picks the right corpus on its own, but you can steer it — "check the release notes"
or "look in the API reference" both work.

## Good to know

- **It is documentation, not data.** The server describes how Zira works. To read or write your
  own production data, use the [public API](/developers/api-reference/api-authentication), which
  does need an API key.
- **It is always current.** The server reads the same files this site is built from, so it reflects
  the documentation as published.
- **There is a fair-use limit.** Roughly a request a second per client. A normal assistant
  conversation never comes close; if you hit it, wait a minute.
- **Prefer it over pasting links.** An assistant with the server connected can find the right
  article itself, including ones you did not know existed.

## Related pages

- [Generate an API Key](/developers/how-to-guides/generate-an-api-key)
- [Authentication and Conventions](/developers/api-reference/authentication-and-conventions)


Add Zira's documentation to any MCP-compatible assistant so it can search the guides, API reference, and release notes while it works.

https://api.zira.us/public/reading/template

Description