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 when an integration needs an export payload for readings over a time range.

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

Meter or data-source ID to export readings for.

meterId

startTime

endTime

startHour

endHour

startOffset

endOffset

Wrapper holding the download URL. It is `null` instead of an object when the range contained no readings.

data

Download URL for the generated CSV. Valid for seven days.

data.fileUrl

Generates a CSV of the readings in the range and returns a download URL for it. The file is finished before you get the URL, so the link works immediately — download it with a plain `GET` and no `Authorization` header.

Export readings data through the downstream meters-data export flow.

Export Readings


## `GET /export`

Use this endpoint when an integration needs an export payload for readings over a 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 | Meter or data-source ID to export readings for. |
| `startTime` | string | no | Start time for time mode A. |
| `endTime` | string | no | End time for time mode A. |
| `startHour` | string | no | Start hour for time mode B. |
| `endHour` | string | no | End hour for time mode B. |
| `startOffset` | string | no | Start offset for time mode B. |
| `endOffset` | string | no | End offset for time mode B. |

## Response

`200 OK`

Generates a CSV of the readings in the range and returns a download URL for it. The file is finished before you get the URL, so the link works immediately — download it with a plain `GET` and no `Authorization` header.

```json
{
  "data": {
    "fileUrl": "https://prod-exports-lightapp.s3.us-west-2.amazonaws.com/Line%201%20Water%20Meter_2026-01-01T00%3A00%3A00.000Z_2026-01-08T00%3A00%3A00.000Z.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=%3Ccredential%3E&X-Amz-Date=20260114T091500Z&X-Amz-Expires=604800&X-Amz-Security-Token=%3Ctoken%3E&X-Amz-Signature=%3Csignature%3E&X-Amz-SignedHeaders=host"
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data` | object (nullable) | Wrapper holding the download URL. It is `null` instead of an object when the range contained no readings. |
| `data.fileUrl` | string | Download URL for the generated CSV. Valid for seven days. |

### Good to know

- An empty range returns `200` with `data` set to `null`. Check for that before reading `data.fileUrl`.
- The download URL is valid for seven days.
- The file is a CSV whose first column is `timestamp`, followed by the data source’s metric names. Timestamps are in the data source’s site time zone — unlike `GET /reading`, which returns UTC.
- The whole range is exported with no row cap, and the request is synchronous with about a 30-second budget. Export wide ranges a day or a week at a time.
- Unlike `GET /reading`, this endpoint ignores `limit` and `sortDesc`.
- Confirm that `data.fileUrl` is actually present rather than relying on the `200` alone.

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



Connect Zira to Claude and you can ask about your plant in plain language:

```text
Why did the trim saw stall last night? Check its readings around 22:00.
```

```text
Open a task for maintenance on line 3, high priority, due tomorrow.
```

Claude reads the data itself and does the work in Zira. You do not paste readings in or copy
results out.

This is different from the [documentation MCP server](/developers/how-to-guides/connect-the-documentation-mcp-server),
which teaches Claude *how Zira works*. This one gives Claude access to *your Zira data*. Most teams
want both.

## The quick way

Zira can set this up for you. In Zira, click your **profile picture** in the top right and choose
**Connect to Claude** — or go straight to [my.zira.us/connect](https://my.zira.us/connect).

1. Choose the site you want Claude to work with.
2. Choose whether Claude may make changes, or only read.
3. Click **Connect to Claude**.
4. Pick your client, click **Copy**, and paste what you copied where it tells you.

That is the whole setup.

**One connection covers one site.** If you look after several sites, come back and connect each one
you want Claude to reach — there is no single connection that covers them all.

Everything below is the manual version, for integrators who would rather assemble it themselves.

---

## The manual way

### What you need

An **API key**. It identifies which Zira data the connection can reach, and you can revoke it at
any time.

### Step 1 — Get an API key

1. In Zira, open **Channels** and go to the relevant channel or company.
2. Open the **Applications** tab.
3. Click the add action.
4. Name it something you will recognise later — **Claude**.
5. Generate the key and **copy it before closing the dialog**. It is shown once.

The key can only reach the site and company it was created under. If you want Claude limited to one
part of your operation, create the key there.

### Step 2 — Add the connection in Claude

#### Claude Code

```bash
claude mcp add --transport http zira https://my.zira.us/api/mcp --header "Authorization: Bearer YOUR-API-KEY"
```

#### Clients configured with a JSON file

```json
{
  "mcpServers": {
    "zira": {
      "type": "http",
      "url": "https://my.zira.us/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR-API-KEY"
      }
    }
  }
}
```

Replace `YOUR-API-KEY` with the key from step 1.

Claude Code picks the connection up in your next session. Claude Desktop reads its config file when
it starts, so restart it. Other clients vary — reload yours if the tools do not appear.

### Step 3 — Try it

Ask something only your Zira data can answer:

```text
List my data sources.
```

If Claude comes back with your real data sources, you are connected.

## Read-only connections

To let Claude look but never change anything, add `?mode=read` to the URL:

```text
https://my.zira.us/api/mcp?mode=read
```

That connection can query readings, data sources, tasks and files, and cannot post, create, or
update anything. It is a good default for a first trial, or for anyone who only needs answers.

## What Claude can do

**Look at things** — read a data source and its schema, query and export readings, list and search
tasks, fetch a file, get an import URL.

**Change things** (unless you used `?mode=read`) — post readings, create and update tasks, post to a
channel, set a device's status, start a file upload.

The tools that change things are marked as such, so Claude asks before using them. Treat that prompt
as a real confirmation: **creating a task notifies the assignee, and posting to a channel is visible
to everyone following it.**

## Good to know

- **The key is the connection.** Anyone holding it has the access it was created with. Store it the
  way you would a password, and revoke it from the **Applications** tab if it leaks or if you stop
  using it.
- **Ask for names, not IDs.** "The bandsaw in Plant 2" is enough — Claude searches for it and finds
  the ID itself.
- **Narrow your time ranges.** "Last night between 21:00 and 23:00" gets a fast, precise answer;
  "this year" returns far more than Claude can read at once.
- **It cannot see everything.** The connection covers the data sources, readings, tasks and files
  the API exposes. Dashboards, forms and vision models are not reachable this way.

## Related pages

- [Connect the Documentation MCP Server](/developers/how-to-guides/connect-the-documentation-mcp-server)
- [Generate an API Key](/developers/how-to-guides/generate-an-api-key)
- [Authentication and Conventions](/developers/api-reference/authentication-and-conventions)


Let Claude read your production data and act in Zira — ask about a line's readings, find a task, or open one — by connecting Zira as a tool.

Connect Zira to Claude


## `GET /import`

Use this endpoint to bulk-load readings for one data source from a CSV file. It returns a pre-signed URL that you upload the file to; Zira imports it in the background once the file lands.

## 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 the readings will be imported into. |
| `timestampFormat` | string | no | Format of the timestamp column in your CSV, e.g. `MM/DD/YYYY HH:mm:ss`. Leave it off to let Zira detect the format. |

## Response

`200 OK`

Returns a single pre-signed URL to upload your CSV file to. Upload the raw file with an HTTP `PUT`, and send no authentication headers with it — the URL is already signed.

```json
{
  "data": {
    "fileUrl": "https://prod-imports-lightapp.s3.us-west-2.amazonaws.com/120/1/774/17794_.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=%3Ccredential%3E&X-Amz-Date=20260114T091500Z&X-Amz-Expires=3600&X-Amz-Security-Token=%3Ctoken%3E&X-Amz-Signature=%3Csignature%3E&X-Amz-SignedHeaders=host&x-id=PutObject"
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | Wrapper holding the upload URL. Never an array, never paginated. |
| `data.fileUrl` | string | The URL to upload your CSV to. Treat it as opaque, single-use and time-limited — do not parse it or try to re-sign it. |

### Good to know

- Upload with `PUT` and the raw CSV as the request body — the URL is signed for `PUT`, so a multipart or `POST` upload will not work. Do not send an `Authorization` header with the upload; the signature in the URL is the authorisation.
- The URL is valid for one hour. Request a fresh one after that.
- Build your CSV header row from `GET /reading/template` for the same data source. Columns are matched by name rather than position, and only `timestamp` is mandatory.
- Every call to this endpoint starts a new import run and the URL points at one fixed file path for one data source, so request a URL only when you are about to use it.
- Importing is asynchronous. A successful upload means the file arrived, not that the readings are stored — an empty file is discarded without notice.
- Treat an empty `fileUrl` as a failure and retry, rather than uploading to it.
- An unknown or inaccessible `meterId` comes back as `401`, not `404`.

## Importing readings from a CSV (the full flow)

1. [Download Template](/developers/api-reference/get-reading-template) — learn the exact columns for
   this data source.
2. Fill in one row per reading, keeping the column order.
3. Call this endpoint to get an upload URL.
4. `PUT` the file to `data.fileUrl`, with the raw CSV as the body and no authentication headers.

Importing then happens in the background. A successful upload means the file arrived — not that the
readings are stored yet.

Prefer [Add Readings](/developers/api-reference/add-readings) when you want to push readings as JSON
instead of uploading a 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. |


Get a one-hour upload URL for bulk-importing readings from a CSV file.

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

Description