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

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

Data source the readings will be imported into.

meterId

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.

timestampFormat

Wrapper holding the upload URL. Never an array, never paginated.

data

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.

data.fileUrl

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.

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

Get Import URL


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


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

Export Readings


## `POST /files/signed-uploads/create`

Use this endpoint when a client needs upload instructions and metadata for a direct file upload.

## 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 the file metadata needed to create a signed upload request.

```json
{
  "name": "field-tag.pdf",
  "fileType": "pdf",
  "fileSize": 1024,
  "fileSizeLoose": true,
  "site": {
    "id": "1512"
  },
  "company": {
    "id": "1216"
  },
  "deviceId": "43510",
  "channelId": "45187"
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Original file name, including extension. |
| `fileSize` | number | yes | File size in bytes. Must be 100 B to 100 MB, and must match the file you upload, unless `fileSizeLoose` is true. |
| `company` | object | no | Company that owns the file, as `{ id }`. Required unless you send `conversation` instead. |
| `site` | object | no | Site that owns the file, as `{ id }`. Optional, and not allowed alongside `conversation`. |
| `conversation` | object | no | Conversation that owns the file, as `{ id }`. Use this instead of `company`/`site` — never both. |
| `fileType` | string | no | File extension. Send this or `fileMimeType`; with neither, the file is stored as `.bin`. |
| `fileMimeType` | string | no | Explicit MIME type. Takes precedence over `fileType` and becomes the required `Content-Type` of the upload. |
| `fileSizeLoose` | boolean | no | When true, `fileSize` is treated as advisory rather than checked against the bytes you upload. |
| `deviceId` | string | no | Data source to attach the file to. Only takes effect when `assetType` is sent too. |
| `assetType` | string | no | What kind of asset this is for the data source. Required alongside `deviceId` for the attachment to happen. |
| `channelId` | string | no | Channel to attach the file to. |
| `originProperties` | object | no | Your own metadata, stored with the file and returned by `GET /files/{fileId}`. Put an identifier here to match the file back to your record. |

## Response

`200 OK`

Returns an upload form to send your file to — `data.signedUrl.url` is where it goes, `data.signedUrl.fields` are the form fields that must accompany it, and `data.name` is the temporary name the file lands under. Nothing exists in Zira yet at this point.

```json
{
  "data": {
    "signedUrl": {
      "url": "https://user-documents-prod.s3.us-west-2.amazonaws.com/",
      "fields": {
        "Content-Type": "application/pdf",
        "bucket": "user-documents-prod",
        "key": "temp/field-tag_1783364043007.pdf",
        "x-amz-meta-metadata": "<json metadata string>",
        "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
        "X-Amz-Credential": "<credential>",
        "X-Amz-Date": "20260114T093403Z",
        "X-Amz-Security-Token": "<token>",
        "Policy": "<base64 policy>",
        "X-Amz-Signature": "<signature>"
      }
    },
    "name": "field-tag_1783364043007.pdf"
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.signedUrl.url` | string | Where to send the file. Upload with a multipart `POST` to this URL. |
| `data.signedUrl.fields` | object | Form fields for the upload. Include every one of them in the multipart body, and add the file part last. |
| `data.name` | string | The unique temporary name the upload lands under. It is not the name the file ends up with — Zira stores it under the original `name` you sent — so use this only to recognise your own upload in flight. |

### Good to know

- This call does not create anything in Zira and does not return a file ID. The file record is created after your upload lands, so there is nothing to look up until then.
- A signing failure is not reported as an error: you get a `200` with `signedUrl` set to `null`. Check that `data.signedUrl` is present before using it.
- To match the file back to your own record afterwards, put your own identifier in `originProperties` — it is stored with the file and comes back on `GET /files/{fileId}`.
- The upload form expires five minutes after this call. Request it immediately before uploading, not in advance.
- Unless you send `fileSizeLoose: true`, `fileSize` must be between 100 bytes and 100 MB, and the file you upload must be exactly that many bytes.
- A successful upload answers `204` (or `201`) from storage with an empty body. Do not send `x-api-key` with the upload — the form fields are the authorisation.
- Either `company` (optionally with `site`) or `conversation` — never both, and `site` is not allowed with `conversation`. Only `name` and `fileSize` are always required.
- To attach the file to a data source you must send both `deviceId` and `assetType`. `deviceId` on its own does nothing.
- The body is strict: an unknown field, or any query string at all, fails with `400`. Inline base64 file content is not supported.

## Uploading the file (step 2)

`POST` the file to `data.signedUrl.url` as `multipart/form-data`. Add every entry from
`data.signedUrl.fields` as a form field, then append the file bytes as a field named `file` — last.
Do **not** send the `x-api-key` header to storage; the signed fields are the authorisation.

A successful upload answers `204 No Content` (or `201`) with an empty body.

Storage does not know anything about Zira, so it cannot give you a file ID. The Zira file record is
created afterwards, when the uploaded object is processed. To find the file later, either match on
`data.name` or put your own identifier in `originProperties` — it comes back on
[Get File](/developers/api-reference/get-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. |


Create signed upload details for client-side file upload flows.

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

Description