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 either one post object or an array of post objects.

Hello world!

Optional title shown above the post content.

title

content

Target channel ID where the post will be created.

toChannelId

Set to true to avoid notifying followers about this post.

skipNotifications

Optional structured payload attached to the post.

payload

Optional grouping key for related post events.

groupingKey

Optional image asset reference to attach to the post.

imageId

Optional priority reference for the post.

priorityId

hashtags

Optional call-to-action objects attached to the post.

ctas

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.

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

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.

data

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.

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

Add Post


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



## `GET /data-sources/{id}`

Purpose:

- return one data source or device

Notes:

- can include schema and last-reading data depending on request options

## `GET /data-sources`

Purpose:

- return a paginated list of data sources or devices

Use this endpoint for integration-side browsing or sync workflows.

## `PUT /devices/modbus/{id}`

Purpose:

- update Modbus settings for a device

Use this when your integration manages device communication settings.

## `POST /files/attach/device/{id}`

Purpose:

- attach files to a device

Behavior:

- serializes nested settings and status objects where needed

## `POST /devices/status/{id}`

Purpose:

- write CV device status
- generate diagnostic status alerts in cache

## `POST /test/{id}`

Purpose:

- support or test utility endpoint that writes CV settings through the `put_device_cv` flow

Warning:

- treat this as a test/support endpoint, not a stable public integration contract unless explicitly approved


Reference the endpoints used to query data sources and update device-related configuration or status.

Data Sources and Device APIs


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


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

Property	Required	Type	Example	Description
title	Optional	string	`Hello world!`	Optional title shown above the post content.
content	Required	string	`This is my message`	Main post body text.
toChannelId	Required	string	`14727`	Target channel ID where the post will be created.
skipNotifications	Optional	boolean	`true`	Set to true to avoid notifying followers about this post.
payload	Optional	object	`{ ... }`	Optional structured payload attached to the post.
groupingKey	Optional	string	`inspection-2026-05-26`	Optional grouping key for related post events.
imageId	Optional	string	`8831`	Optional image asset reference to attach to the post.
priorityId	Optional	string	`2`	Optional priority reference for the post.
hashtags	Optional	string[]	`["inspection", "night-shift"]`	Optional hashtags to attach to the post.
ctas	Optional	object[]	`[{ ... }]`	Optional call-to-action objects attached to the post.

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

Description