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 a `status` object describing the device’s current health. Report the full set of fields every time.

The device’s current health and operational state. Its fields are listed below.

status

Battery charge as a percentage. A low value raises an alert unless `isCharging` is true.

status.battery

Whether the device is currently charging.

status.isCharging

status.onLine

Whether the device itself is powered on and running.

status.deviceOn

status.cameraOn

Whether Wi-Fi is connected. Send at least one connected network flag.

status.wifiConnected

status.cellularConnected

status.ethernetConnected

Device temperature in °C. A high value raises an alert.

status.temperature

status.version

Use this endpoint when an integration needs to report device health or operational state for a specific CV device.

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 data source whose device status you are reporting.

data

Returns the fixed string `"SUCCESS"` once the status has been stored. Nothing about the device or the alerts that were raised is echoed back — a `200` means "status recorded", not "device healthy".

Update CV device status and trigger diagnostic alert evaluation.

Update Device Status


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

Use this endpoint when an integration needs to report device health or operational state for a specific CV device.

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

## Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | ID of the data source whose device status you are reporting. |

## Request body

Send a `status` object describing the device’s current health. Report the full set of fields every time.

```json
{
  "status": {
    "battery": 82,
    "isCharging": true,
    "onLine": true,
    "deviceOn": true,
    "cameraOn": true,
    "wifiConnected": true,
    "cellularConnected": false,
    "temperature": 31.5,
    "version": "2.14.0"
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | object | yes | The device’s current health and operational state. Its fields are listed below. |
| `status.battery` | number | no | Battery charge as a percentage. A low value raises an alert unless `isCharging` is true. |
| `status.isCharging` | boolean | no | Whether the device is currently charging. |
| `status.onLine` | boolean | no | Whether the device can reach Zira. |
| `status.deviceOn` | boolean | no | Whether the device itself is powered on and running. |
| `status.cameraOn` | boolean | no | Whether the camera is active. |
| `status.wifiConnected` | boolean | no | Whether Wi-Fi is connected. Send at least one connected network flag. |
| `status.cellularConnected` | boolean | no | Whether a cellular connection is up. |
| `status.ethernetConnected` | boolean | no | Whether a wired connection is up. |
| `status.temperature` | number | no | Device temperature in °C. A high value raises an alert. |
| `status.version` | string | no | Software version running on the device. |

## Response

`200 OK`

Returns the fixed string `"SUCCESS"` once the status has been stored. Nothing about the device or the alerts that were raised is echoed back — a `200` means "status recorded", not "device healthy".

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

| Field | Type | Description |
| --- | --- | --- |
| `data` | string | Always the literal `"SUCCESS"` on a 200. |

### Good to know

- Status values are not validated — they are evaluated. An unhealthy or missing value raises an alert for the device instead of failing your request, and you still get a `200`.
- Because of that, send the full set every time: `battery`, `onLine`, `deviceOn`, `cameraOn`, `wifiConnected` and `cellularConnected`. A field you leave out is treated as if it were bad news.
- Re-reporting a healthy status is how you clear alerts you raised earlier — Zira resolves an alert once the new status no longer triggers it.
- The device is identified by the path segment, not by a `deviceId` in the body.
- The reported status shows up in Zira as the data source’s device status.
- Errors from this endpoint are unusually detailed compared with the rest of the API. Do not treat that detail as a stable contract, and do not show it to end users.

## 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 /tasks`

Use this endpoint to browse or sync tasks. Results are paged with a cursor, and you can narrow them by site, status, priority, assignee or type.

## 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 |
| --- | --- | --- | --- |
| `limit` | number | no | Page size. Always send it, so that a missing `lastValue` reliably means you have reached the end. |
| `lastValue` | string | no | Cursor for the next page. Pass the `lastValue` from the previous response back verbatim. |
| `textSearch` | string | no | Free-text search over task names. Keep sending the same `textSearch` while paging through its results. |
| `sortDesc` | boolean | no | Reverse the sort order. |
| `siteIds` | string | no | Comma-separated site IDs to filter by, e.g. `1512,1513`. |
| `statusIds` | string | no | Comma-separated status IDs to filter by, e.g. `5,15`. |
| `priorityIds` | string | no | Comma-separated priority IDs to filter by — `5` Low, `10` Medium, `15` High. |
| `assigneeIds` | string | no | Comma-separated user IDs to filter by assignee. |
| `typeIds` | string | no | Comma-separated task type IDs to filter by. |

## Response

`200 OK`

Returns a page of task objects in `data`, with an opaque `lastValue` cursor beside it. Each task carries its status, site, priority and assignee as small `{ id, name }` objects, and the assignee is expanded with their name, email and avatar URLs.

```json
{
  "data": [
    {
      "id": "9901",
      "name": "Replace inlet filter on Line 1",
      "description": "Differential pressure above threshold for two shifts.",
      "dueDate": "2026-01-20",
      "doneDate": null,
      "progressDate": null,
      "timeSpent": "@ 0",
      "formatedTimeSpent": "0h:0m",
      "timeToRespond": null,
      "timeToResolve": null,
      "timeToDueDate": "6d:0h:0m",
      "assignee": {
        "id": "318",
        "firstName": "Alex",
        "lastName": "Rivera",
        "name": "Alex Rivera",
        "image": {
          "id": "20514",
          "url": "https://prod-images-zira.s3.us-west-2.amazonaws.com/<hash>?X-Amz-Expires=604800&X-Amz-Signature=<signature>&x-id=GetObject",
          "thumbnailUrl": "https://prod-images-zira.s3.us-west-2.amazonaws.com/<hash>_thumbnail?X-Amz-Expires=604800&X-Amz-Signature=<signature>&x-id=GetObject"
        },
        "channelId": "3024",
        "username": "alex.rivera@example.com",
        "email": "alex.rivera@example.com"
      },
      "status": {
        "id": "5",
        "name": "To Do"
      },
      "site": {
        "id": "1512",
        "name": "Fresno Plant",
        "channelId": "45187"
      },
      "system": null,
      "device": null,
      "priority": {
        "id": "10",
        "name": "Medium"
      },
      "type": {
        "id": "1",
        "name": "Manual"
      },
      "auditInfo": {
        "createdBy": {
          "id": "318"
        },
        "createdDate": "2026-01-14T09:15:00.000000Z",
        "lastModifiedBy": {
          "id": "318"
        },
        "lastModifiedDate": "2026-01-14T09:15:00.000000Z"
      },
      "timeSpentMandatory": false,
      "resolution": null,
      "resolutionDescription": null,
      "cost": null,
      "estimatedTime": null,
      "postId": 240873,
      "hashtags": null
    }
  ],
  "lastValue": "eyJhdWRpdEluZm8uY3JlYXRlZERhdGUiOiIyMDI2LTAxLTE0VDA5OjE1OjAwWiIsImlkIjoiOTkwMSJ9"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data` | array (nullable) | A page of tasks. `null` — not an empty array — when nothing matched. |
| `data[].id` | string | Task ID, as a string. |
| `data[].name` | string | Task title. |
| `data[].description` | string (nullable) | Plain-text description. |
| `data[].dueDate` | string (nullable) | Due date, as `YYYY-MM-DD`. |
| `data[].doneDate` | string (nullable) | When the task was completed. `null` while it is still open. |
| `data[].timeSpent` | string | Raw accumulated time. `formatedTimeSpent` is the display form, e.g. `2h:15m`. |
| `data[].timeToResolve` | string (nullable) | How long the task took to close, e.g. `19d:8h:27m`. `null` until it is done. |
| `data[].assignee` | object (nullable) | The assigned user, expanded with `name`, `email`, `channelId` and an `image` holding ready-to-use `url` and `thumbnailUrl`. |
| `data[].status` | object | `{ id, name }`, e.g. `To Do`, `On Hold`, `Done`. |
| `data[].site` | object | `{ id, name, channelId }` for the site that owns the task. |
| `data[].priority` | object (nullable) | `{ id, name }` — `5` Low, `10` Medium, `15` High. |
| `data[].type` | object | `{ id, name }` — `1` Manual, `3` for a task tied to a data source. |
| `data[].device` | object (nullable) | The data source the task is about, when it has one. |
| `data[].auditInfo` | object | `createdBy`, `createdDate`, `lastModifiedBy`, `lastModifiedDate`. |
| `data[].postId` | number | ID of the feed post Zira created for this task. A number, while `id` is a string. |
| `lastValue` | string | Opaque cursor for the next page. Pass it back as `?lastValue=…`. |

### Good to know

- Tasks carry a long tail of optional fields that are `null` on most installations — `taskType2`, `department`, `workCenter`, `attr1`–`attr3`, `assignee2`–`assignee4`, `category`, `application`. They are omitted from the example above but do appear in the payload.
- New fields get added to tasks over time, so parse defensively rather than rejecting unknown keys.
- IDs are strings, except `postId`, which is a number. Convert before comparing.
- Image and file URLs are pre-signed and time-limited — fetch them soon after reading, and re-request the task rather than storing them.
- Do not treat the presence of `lastValue` as proof that more data exists. Keep paging until `data` comes back `null`, or until you receive fewer rows than the `limit` you asked for.
- An empty page is `{"data": null}`, not `{"data": []}`.

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


List tasks the API key can see, a page at a time.

Get Tasks


## `GET /data-sources`

Use this endpoint to discover data sources when you do not already know their IDs. Results are paged with a cursor and can be filtered by site, usage or name. Once you have the IDs, `GET /data-sources/{id}` gives you the full record.

## 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 |
| --- | --- | --- | --- |
| `limit` | number | no | Page size. Always send it, so that a missing `lastValue` reliably means you have reached the end. |
| `lastValue` | string | no | Cursor for the next page. Pass the `lastValue` from the previous response back verbatim. |
| `siteIds` | string | no | Comma-separated site IDs to restrict the list to, e.g. `1512,1513`. |
| `meterIds` | string | no | Comma-separated data source IDs, when you want a known set rather than a browse. |
| `applyingIds` | string | no | Comma-separated usage IDs — `1` Sensor, `2` form, `7` AI Vision. |
| `textSearch` | string | no | Free-text search over data source names. Keep sending the same value while paging through its results. |
| `withLastReadings` | boolean | no | Adds each row’s most recent reading. Any value at all turns this on — omit the parameter to leave it off. |
| `withDetails` | boolean | no | Expands each row to all of its metrics. Any value at all turns this on — omit the parameter to leave it off. |
| `onlyMain` | boolean | no | Send the literal string `true` to restrict each row to its main metric. |

## Response

`200 OK`

Returns a page of data sources in `data`, with an opaque `lastValue` cursor beside it. Each row is a summary — enough to identify a data source and decide which ones you care about. Fetch the full record with `GET /data-sources/{id}`.

```json
{
  "data": [
    {
      "id": "43510",
      "name": "Line 1 Label Counter",
      "validationStatus": 20,
      "type": {
        "id": "50",
        "name": "Form",
        "ordinal": 1
      },
      "site": {
        "id": "1512",
        "name": "Fresno Plant",
        "channelId": "45187"
      },
      "applying": {
        "id": "7",
        "name": "AI Vision",
        "channelId": null
      },
      "channelId": "67363",
      "isShared": false
    }
  ],
  "lastValue": "eyJ0eXBlT3JkaW5hbCI6MSwibmFtZSI6IkxpbmUgMSBMYWJlbCBDb3VudGVyIiwiaWQiOiI0MzUxMCJ9"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data` | array (nullable) | A page of data sources. `null` — not an empty array — when nothing matched. |
| `data[].id` | string | Data source ID — use it with `GET /data-sources/{id}`, `GET /reading` and `POST /reading`. |
| `data[].name` | string | Display name. |
| `data[].validationStatus` | number (nullable) | Where the data source is in validation: `10` Pending Validation, `20` Valid, `30` Invalid. A number here, while `GET /data-sources/{id}` returns the same thing as an object. |
| `data[].type` | object | `{ id, name, ordinal }` — what kind of data source it is. |
| `data[].site` | object | `{ id, name, channelId }` for the owning site. |
| `data[].applying` | object (nullable) | `{ id, name }` — how it is used: `1` Sensor, `2` form, `7` AI Vision. |
| `data[].channelId` | string (nullable) | Channel that carries this data source’s feed. |
| `data[].isShared` | boolean | Whether the data source is shared with other sites. |
| `lastValue` | string | Opaque cursor for the next page. Pass it back as `?lastValue=…`. |

### Good to know

- Rows always carry `id`, `name`, `validationStatus`, `type`, `site` and `isShared`. Other fields depend on the data source and on the flags you send, so read defensively.
- Add `withLastReadings` to get each row’s latest reading inline, or `withDetails` to expand every metric — either saves a follow-up call per data source.
- Do not treat the presence of `lastValue` as proof that more data exists. Keep paging until `data` comes back `null`, or until you receive fewer rows than the `limit` you asked for.
- The list is ordered by type, then name, then ID, and the cursor is built from those three. There is no way to change the sort.
- An empty result is `{"data": null}`, not `{"data": []}`.
- To map metric IDs to names for a data source, call `GET /data-sources/{id}?withSchema=true`.

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


Browse the data sources the API key can see, a page at a time.

Property	Required	Type	Example	Description
status	Required	object	`{ "battery": 82, "onLine": true, ... }`	The device’s current health and operational state. Its fields are listed below.
status.battery	Optional	number	`82`	Battery charge as a percentage. A low value raises an alert unless `isCharging` is true.
status.isCharging	Optional	boolean	`true`	Whether the device is currently charging.
status.onLine	Optional	boolean	`true`	Whether the device can reach Zira.
status.deviceOn	Optional	boolean	`true`	Whether the device itself is powered on and running.
status.cameraOn	Optional	boolean	`true`	Whether the camera is active.
status.wifiConnected	Optional	boolean	`true`	Whether Wi-Fi is connected. Send at least one connected network flag.
status.cellularConnected	Optional	boolean	`false`	Whether a cellular connection is up.
status.ethernetConnected	Optional	boolean	`false`	Whether a wired connection is up.
status.temperature	Optional	number	`31.5`	Device temperature in °C. A high value raises an alert.
status.version	Optional	string	`2.14.0`	Software version running on the device.

https://api.zira.us/public/devices/status/{id}

Description