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

field-tag.pdf

name

File size in bytes. Must be 100 B to 100 MB, and must match the file you upload, unless `fileSizeLoose` is true.

fileSize

Company that owns the file, as `{ id }`. Required unless you send `conversation` instead.

company

Site that owns the file, as `{ id }`. Optional, and not allowed alongside `conversation`.

site

Conversation that owns the file, as `{ id }`. Use this instead of `company`/`site` — never both.

conversation

File extension. Send this or `fileMimeType`; with neither, the file is stored as `.bin`.

fileType

Explicit MIME type. Takes precedence over `fileType` and becomes the required `Content-Type` of the upload.

fileMimeType

When true, `fileSize` is treated as advisory rather than checked against the bytes you upload.

fileSizeLoose

Data source to attach the file to. Only takes effect when `assetType` is sent too.

deviceId

What kind of asset this is for the data source. Required alongside `deviceId` for the attachment to happen.

assetType

channelId

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.

originProperties

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

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

field-tag_1783364043007.pdf

Where to send the file. Upload with a multipart `POST` to this URL.

data.signedUrl.url

Form fields for the upload. Include every one of them in the multipart body, and add the file part last.

data.signedUrl.fields

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.

data.name

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.

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

Create Signed Upload


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



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

Get Import URL


## `GET /files/{fileId}`

Use this endpoint when you have a file ID and need its metadata plus a URL you can download from directly.

## 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 |
| --- | --- | --- | --- |
| `fileId` | string | yes | ID of the file to fetch. |

## Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `resolveFiles` | boolean | no | Defaults to true. Set it to `false` to get the metadata without generating a download URL — the `file` field then comes back empty. |

## Response

`200 OK`

Returns the file’s metadata plus a pre-signed download URL. Note the URL is in the `file` field — not `url` or `fileUrl` — and the owning company and site come back as `{ id, name }` objects.

```json
{
  "data": {
    "id": "8690",
    "name": "line-1-inspection.png",
    "fileType": "png",
    "fileSize": 1063821,
    "createdDate": "2026-01-11T08:57:55.235393+00:00",
    "createdBy": 318,
    "origin": null,
    "originProperties": null,
    "company": {
      "id": "1216",
      "name": "Northwind Manufacturing"
    },
    "site": {
      "id": "1512",
      "name": "Fresno Plant"
    },
    "conversation": null,
    "file": "https://user-documents-prod.s3-accelerate.amazonaws.com/1216/1512/line-1-inspection.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=604800&X-Amz-Signature=<signature>&x-id=GetObject"
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.id` | string | File ID, as a string. |
| `data.name` | string | File name, including its extension. |
| `data.fileType` | string | File extension, e.g. `png`, `pdf`, `csv`. |
| `data.fileSize` | number | Size in bytes. |
| `data.createdDate` | string | When the file was created, with a UTC offset. |
| `data.createdBy` | number | ID of the user who uploaded it. A number here, unlike most IDs in this API. |
| `data.company` | object (nullable) | `{ id, name }` for the owning company. |
| `data.site` | object (nullable) | `{ id, name }` for the owning site. |
| `data.conversation` | object (nullable) | Set instead of `company`/`site` when the file belongs to a conversation. |
| `data.origin` | string (nullable) | Where the file came from, when Zira recorded it. |
| `data.originProperties` | object (nullable) | The metadata you passed as `originProperties` when the upload was created — useful for matching a file back to your own record. |
| `data.file` | string | Pre-signed download URL. Fetch it with a plain `GET` and no authentication headers. This is the field to read — there is no `url` or `fileUrl`. |

### Good to know

- The download URL is time-limited. Fetch it soon after reading, and re-request the file rather than storing the URL.
- A file ID that does not exist, or that this API key cannot see, comes back as an error rather than as `data: null`.
- Send no query parameters other than `resolveFiles` — anything else is passed through to the lookup and fails.

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


Fetch one file by ID, with a ready-to-use download URL.

Property	Required	Type	Example	Description
name	Required	string	`field-tag.pdf`	Original file name, including extension.
fileSize	Required	number	`1024`	File size in bytes. Must be 100 B to 100 MB, and must match the file you upload, unless `fileSizeLoose` is true.
company	Optional	object	`{ "id": "1216" }`	Company that owns the file, as `{ id }`. Required unless you send `conversation` instead.
site	Optional	object	`{ "id": "1512" }`	Site that owns the file, as `{ id }`. Optional, and not allowed alongside `conversation`.
conversation	Optional	object	`{ "id": "8842" }`	Conversation that owns the file, as `{ id }`. Use this instead of `company`/`site` — never both.
fileType	Optional	string	`pdf`	File extension. Send this or `fileMimeType`; with neither, the file is stored as `.bin`.
fileMimeType	Optional	string	`application/pdf`	Explicit MIME type. Takes precedence over `fileType` and becomes the required `Content-Type` of the upload.
fileSizeLoose	Optional	boolean	`true`	When true, `fileSize` is treated as advisory rather than checked against the bytes you upload.
deviceId	Optional	string	`43510`	Data source to attach the file to. Only takes effect when `assetType` is sent too.
assetType	Optional	string	`video`	What kind of asset this is for the data source. Required alongside `deviceId` for the attachment to happen.
channelId	Optional	string	`45187`	Channel to attach the file to.
originProperties	Optional	object	`{ "id": "corr-123" }`	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.

https://api.zira.us/public/files/signed-uploads/create

Description