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 to load one data source and optionally include its schema and last 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

Send the literal string `true` to include the data source’s metric schema. Any other value is treated as false.

withSchema

Send the literal string `true` to include the most recent reading. Any other value is treated as false.

withLastReading

Pending Readings

AI Vision

Alex Rivera

Form

Push

Line 1 Label Counter

Fresno Plant

Pending Validation

data.id

data.name

data.description

Your own identifier for this data source, if one was set.

data.externalId

`{ id, name }` — what kind of data source it is, e.g. `Form`, `Power Meter`.

data.type

`{ id, name }` — how it is used: `1` Sensor, `2` form, `7` AI Vision.

data.applying

`{ id, name, channelId }` for the owning site.

data.site

IANA time zone, e.g. `US/Pacific`. `offset` is the same thing in minutes.

data.tzTimezoneName

`{ id, name }` — where the data source is in validation. In the list endpoint this same field is a bare number.

data.validationStatus

`{ id, name }` — whether it is actively reporting, e.g. `Active`, `Pending Readings`.

data.activityStatus

What collects the data. `collectorType` says whether Zira pulls it or the device pushes it.

data.collector

Seconds of silence after which the data source counts as inactive.

data.inactiveThreshold

Expected seconds between readings. `null` for push sources.

data.readingInterval

Whether collection is currently switched on.

data.collectionEnabled

Channel that carries this data source’s feed.

data.channelId

Per-metric unit choices, as `{ metricId, uomId }`.

data.displayUoms

Only present with `withSchema=true`. Holds `metrics[]`, each with its `metric` `{ id, name }`, `uom`, `displayName` and `isRequired` — this is where you map metric IDs to names.

data.meterSchema

Present on form data sources. Describes the fields operators fill in, with `order`, `required` and a `properties` map.

data.formConfig

Present on camera data sources. Holds vision configuration such as counting lines, shifts and posting intervals.

data.cv

`createdBy`, `createdDate`, `lastModifiedBy`, `lastModifiedDate`.

data.auditInfo

Returns one data source with its identity, location, time zone, collection settings and status. The example below is trimmed — a real payload also carries per-type blocks such as `formConfig` for forms and `cv` for cameras.

Fetch a single data source or device by ID.

Get Data Source


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

Use this endpoint to load one data source and optionally include its schema and last reading.

## Authentication

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

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 to fetch. |

## Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `withSchema` | boolean | no | Send the literal string `true` to include the data source’s metric schema. Any other value is treated as false. |
| `withLastReading` | boolean | no | Send the literal string `true` to include the most recent reading. Any other value is treated as false. |

## Response

`200 OK`

Returns one data source with its identity, location, time zone, collection settings and status. The example below is trimmed — a real payload also carries per-type blocks such as `formConfig` for forms and `cv` for cameras.

```json
{
  "data": {
    "id": "43510",
    "name": "Line 1 Label Counter",
    "description": "Camera 5",
    "externalId": null,
    "type": {
      "id": "50",
      "name": "Form"
    },
    "offset": -420,
    "timezoneId": "3",
    "tzTimezoneName": "US/Pacific",
    "site": {
      "id": "1512",
      "name": "Fresno Plant",
      "channelId": "45187"
    },
    "model": {
      "id": null,
      "name": null
    },
    "manufacturer": null,
    "inactiveThreshold": 1500,
    "validationStatus": {
      "id": "10",
      "name": "Pending Validation"
    },
    "activityStatus": {
      "id": "40",
      "name": "Pending Readings"
    },
    "collector": {
      "id": "29",
      "name": "Form"
    },
    "collectorType": {
      "id": "1",
      "name": "Push"
    },
    "applying": {
      "id": "7",
      "name": "AI Vision"
    },
    "isCustomSchema": true,
    "collectionEnabled": true,
    "readingInterval": null,
    "channelId": "67363",
    "companyId": "1216",
    "isShared": false,
    "isTemplate": false,
    "isDeleted": false,
    "isPrivate": false,
    "displayUoms": [
      {
        "metricId": "81",
        "uomId": "2501"
      },
      {
        "metricId": "86",
        "uomId": "2600"
      }
    ],
    "images": null,
    "files": null,
    "auditInfo": {
      "createdBy": {
        "id": "318",
        "name": "Alex Rivera"
      },
      "createdDate": "2026-01-14T08:36:16.120973Z",
      "lastModifiedBy": {
        "id": "318",
        "name": "Alex Rivera"
      },
      "lastModifiedDate": "2026-01-14T08:36:16.120973Z"
    }
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.id` | string | Data source ID. |
| `data.name` | string | Display name. |
| `data.description` | string (nullable) | Free-text description. |
| `data.externalId` | string (nullable) | Your own identifier for this data source, if one was set. |
| `data.type` | object | `{ id, name }` — what kind of data source it is, e.g. `Form`, `Power Meter`. |
| `data.applying` | object | `{ id, name }` — how it is used: `1` Sensor, `2` form, `7` AI Vision. |
| `data.site` | object | `{ id, name, channelId }` for the owning site. |
| `data.tzTimezoneName` | string | IANA time zone, e.g. `US/Pacific`. `offset` is the same thing in minutes. |
| `data.validationStatus` | object | `{ id, name }` — where the data source is in validation. In the list endpoint this same field is a bare number. |
| `data.activityStatus` | object | `{ id, name }` — whether it is actively reporting, e.g. `Active`, `Pending Readings`. |
| `data.collector` | object (nullable) | What collects the data. `collectorType` says whether Zira pulls it or the device pushes it. |
| `data.inactiveThreshold` | number (nullable) | Seconds of silence after which the data source counts as inactive. |
| `data.readingInterval` | number (nullable) | Expected seconds between readings. `null` for push sources. |
| `data.collectionEnabled` | boolean | Whether collection is currently switched on. |
| `data.channelId` | string | Channel that carries this data source’s feed. |
| `data.displayUoms` | array (nullable) | Per-metric unit choices, as `{ metricId, uomId }`. |
| `data.meterSchema` | object (nullable) | Only present with `withSchema=true`. Holds `metrics[]`, each with its `metric` `{ id, name }`, `uom`, `displayName` and `isRequired` — this is where you map metric IDs to names. |
| `data.formConfig` | object (nullable) | Present on form data sources. Describes the fields operators fill in, with `order`, `required` and a `properties` map. |
| `data.cv` | object (nullable) | Present on camera data sources. Holds vision configuration such as counting lines, shifts and posting intervals. |
| `data.auditInfo` | object | `createdBy`, `createdDate`, `lastModifiedBy`, `lastModifiedDate`. |

### Good to know

- Add `withSchema=true` to get `meterSchema`. That is how you map the numeric metric IDs used by `GET /reading` and `POST /reading` to human-readable names.
- Metrics that Zira calculates for you are left out of the schema, because you cannot write to them.
- Add `withLastReading=true` to get the most recent reading inline, instead of making a separate `GET /reading` call.
- `withSchema=true` on a data source that has no schema fails with a server error rather than returning an empty schema.
- The payload varies by type: forms carry `formConfig`, cameras carry `cv`, metered devices carry connection fields such as `ipAddress`, `port` and `modbus`. Read the blocks you need and ignore the rest.
- Both flags are compared against the literal string `true` — `withSchema=1` or `withSchema=yes` will not work.

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

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.

Get Data Source List


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

https://api.zira.us/public/data-sources/{id}

Description