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.

Send an array of meters, each with one or more timestamped readings keyed by metric ID.

Data source that will receive the readings. Must be a JSON string — a number is rejected.

meterId

One entry per timestamped reading for that data source.

readings

When the reading was taken. Send `null` to use the server’s current time — but the key must be present either way.

readings[].timestamp

Metric IDs mapped to their values. Get the IDs from `GET /data-sources/{id}?withSchema=true`.

readings[].values

Use this endpoint to post readings in the primary SDK ingestion format, with values keyed by metric ID inside each reading.

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

Request body format for the JSON payload.

Content-Type

Always the literal `"SUCCESS"` on a 200. It never carries counts, IDs or per-row detail.

data

Returns the fixed string `"SUCCESS"`. There is no per-reading result and no generated ID, so treat the `200` itself as the signal — there is nothing in the body worth parsing.

Insert meter readings where values are sent as a metric map keyed by metric ID.

Add Readings


## `POST /reading`

Use this endpoint to post readings in the primary SDK ingestion format, with values keyed by metric ID inside each reading.

## Authentication

```http
x-api-key: <your-api-key>
Content-Type: application/json
```

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

## Request body

Send an array of meters, each with one or more timestamped readings keyed by metric ID.

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `meterId` | string | yes | Data source that will receive the readings. Must be a JSON string — a number is rejected. |
| `readings` | object[] | yes | One entry per timestamped reading for that data source. |
| `readings[].timestamp` | string | yes | When the reading was taken. Send `null` to use the server’s current time — but the key must be present either way. |
| `readings[].values` | object | yes | Metric IDs mapped to their values. Get the IDs from `GET /data-sources/{id}?withSchema=true`. |

## Response

`200 OK`

Returns the fixed string `"SUCCESS"`. There is no per-reading result and no generated ID, so treat the `200` itself as the signal — there is nothing in the body worth parsing.

```json
{
  "data": "SUCCESS"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data` | string | Always the literal `"SUCCESS"` on a 200. It never carries counts, IDs or per-row detail. |

### Good to know

- `SUCCESS` means the batch was accepted for ingestion, not that it is stored yet. Allow for a short lag before reading the same values back with `GET /reading`.
- The whole batch is accepted or rejected together. If the API key cannot write to any one data source in the payload, the request fails with `401` and nothing is written.
- Send `"timestamp": null` to have Zira stamp the current time. The key still has to be present — omitting it is a `400`.
- Reading objects take only `timestamp` and `values`; any other key inside a reading is rejected with `400`. Keys you add on the enclosing data-source object are ignored instead.
- Leave out metrics that Zira calculates. Any writable metric you omit from `values` is stored as `null` rather than left at its previous value.
- Do not add a query string to this request — it interferes with body validation and produces a misleading `400`.

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



## `POST /post`

Use this endpoint when an external system needs to publish an update into a Zira channel. The request can send a single post object or an array of post objects.

## Authentication

```http
x-api-key: <your-api-key>
Content-Type: application/json
```

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

## Request body

Send either one post object or an array of post objects.

```json
{
  "title": "Hello world!",
  "content": "This is my message",
  "toChannelId": "14727",
  "skipNotifications": true
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | no | Optional title shown above the post content. |
| `content` | string | yes | Main post body text. |
| `toChannelId` | string | yes | Target channel ID where the post will be created. |
| `skipNotifications` | boolean | no | Set to true to avoid notifying followers about this post. |
| `payload` | object | no | Optional structured payload attached to the post. |
| `groupingKey` | string | no | Optional grouping key for related post events. |
| `imageId` | string | no | Optional image asset reference to attach to the post. |
| `priorityId` | string | no | Optional priority reference for the post. |
| `hashtags` | string[] | no | Optional hashtags to attach to the post. |
| `ctas` | object[] | no | Optional call-to-action objects attached to the post. |

## Response

`200 OK`

Returns the ID of the post that was created, as a bare number under `data`. The post itself is not echoed back, and there is no public endpoint to read it again — so keep this ID if you need to reference the post later.

```json
{
  "data": 240872
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data` | number | ID of the newly created post. It comes back as a JSON number, even though every ID you send in the request body has to be a string. |

### Good to know

- One post per request. Send a single object — an array holding exactly one post also works, but an array of two or more is not supported and fails.
- An empty array creates nothing and returns `{}`, with no `data` key at all.
- Zira sets `fromChannelId` and `postTypeId` itself, from the API key context. Do not send them: any field outside the list above is rejected with `400` and `internalErrorCode` `01-004`.
- Followers are notified after the post is created, so the post exists even when notification delivery fails. Send `skipNotifications: true` to create the post quietly.

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


Create a feed post in a target channel under an API-key integration context.

Add Post


## `GET /reading`

Use this endpoint to retrieve readings for a meter across a validated time range.

## 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 | Data source to read from. |
| `startTime` | string | no | Start of an absolute time range, e.g. `2026-01-14T00:00:00`. Send it together with `endTime`. |
| `endTime` | string | no | End of an absolute time range. Send it together with `startTime`. |
| `startHour` | string | no | Start of a daily window, as `HH:mm:ss`. Part of the relative range — send all four of these together. |
| `endHour` | string | no | End of a daily window, as `HH:mm:ss`. Part of the relative range. |
| `startOffset` | string | no | How far back the relative range starts, as `<amount> <unit>`, e.g. `1 day`. |
| `endOffset` | string | no | How far back the relative range ends, as `<amount> <unit>`, e.g. `0 days`. |
| `limit` | number | no | Maximum number of rows to return. 1 to 500, and 500 by default. |
| `lastValue` | string | no | Cursor for the next page. Pass the `lastValue` string from the previous response back verbatim. |
| `sortDesc` | boolean | no | Order rows by timestamp descending. Newest-first is already the default. |

## Response

`200 OK`

Returns one flat row per reading timestamp, newest first. Metric values are keys named after the metric ID, alongside `meter_id` and `event_date`. An opaque `lastValue` cursor sits next to `data` for fetching the next page.

```json
{
  "data": [
    {
      "33": 0.5,
      "34": 2.5,
      "meter_id": 17794,
      "event_date": "2026-01-14T12:44:20.000000Z"
    },
    {
      "33": 1,
      "34": 2,
      "meter_id": 17794,
      "event_date": "2026-01-14T12:28:36.000000Z"
    },
    {
      "33": null,
      "34": 1.5,
      "meter_id": 17794,
      "event_date": "2026-01-14T05:44:20.000000Z"
    }
  ],
  "lastValue": "eyJldmVudF9kYXRlIjoiMjAyNi0wMS0xNFQwNTo0NDoyMC4wMDAwMDBaIn0="
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data` | array (nullable) | One object per reading timestamp. `null` — not an empty array — when the data source has no readings in the window you asked for. |
| `data[].<metricId>` | number | string | null (nullable) | One key per metric, named with the metric’s ID (e.g. `"33"`). `null` when that metric had no value at that timestamp. Get the ID-to-name mapping from `GET /data-sources/{id}` with `withSchema=true`. |
| `data[].meter_id` | number | ID of the data source the row belongs to. A number here, even though the `meterId` you send in the query is a string. |
| `data[].event_date` | string | Timestamp of the reading, UTC with microsecond precision. This is also the field pagination sorts on. |
| `lastValue` | string | Opaque cursor for the next page. Pass it back verbatim as `?lastValue=…`. |

### Good to know

- Rows are flat and keyed by metric ID. There is no nested `readings` array.
- Do not treat the presence of `lastValue` as proof that more data exists — on this endpoint it comes back on every non-empty page, including the last one. Keep paging until `data` is `null`, or until you get fewer rows than the `limit` you asked for.
- Newest-first is the effective default ordering.
- `limit` accepts 1 to 500 and defaults to 500, so 500 rows is the largest page you can get.
- Metric filtering is not available on this endpoint — every metric on the data source comes back on every row.

## Paging through readings

Send a `limit`, then pass the `lastValue` from each response back as `?lastValue=…` to get the
next page. Treat the cursor as opaque — do not decode or build one yourself.

Stop when `data` comes back `null`, or when you receive fewer rows than the `limit` you asked
for. On this endpoint a `lastValue` is returned even on the final page, so its presence alone does
not mean more data exists.

## Mapping metric IDs to names

Row keys are metric IDs. Call
[Get Data Source List](/developers/api-reference/get-data-source-list) — every data source comes back
with its `meterSchema`, where `metrics[].metric.id` is the key you see here and
`metrics[].displayName` is its human-readable name.

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


Read meter data with validated time-range filters.

Property	Required	Type	Example	Description
meterId	Required	string	`"43510"`	Data source that will receive the readings. Must be a JSON string — a number is rejected.
readings	Required	object[]	`[{ "timestamp": …, "values": … }]`	One entry per timestamped reading for that data source.
readings[].timestamp	Required	string	`"2026-01-14T10:00:00Z"`	When the reading was taken. Send `null` to use the server’s current time — but the key must be present either way.
readings[].values	Required	object	`{ "33": 12.4, "34": 55 }`	Metric IDs mapped to their values. Get the IDs from `GET /data-sources/{id}?withSchema=true`.

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

Description