
Use this guide when you need a new application key for an integration or external client.

## Create the key from the UI

1. Open **Channels** and go to the relevant channel or company context.
2. Open the **Applications** tab.
3. Click the add action.
4. Enter a name and an optional description.
5. Generate the API key.
6. Copy the key before closing the dialog.

## Important notes

- The key is typically shown at creation time, so copy it immediately.
- Use a clear name so other developers know what the key is for.
- Remove unused keys to reduce clutter and risk.

## Suggested usage

- Store the key in your team’s secret manager.
- Do not hardcode it in frontend code or commit it to the repository.

![Generate API key flow](/developers/how-to-guides/generate-an-api-key/01-overview.png)


Create an application key for integrations and copy it during creation before closing the dialog.

Generate an API Key


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

Get File


## `GET /files/{fileId}`

Purpose:

- fetch one file by ID
- return resolved metadata and file URLs

Path params:

- `fileId`

Notes:

- the handler remaps `fileId` to the internal `id` field before querying

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

Purpose:

- create signed upload instructions for client-side upload flows

Request notes:

- validates against the signed-upload schema
- if `originProperties` is sent as an object, it is stringified before processing

Typical body:

```json
{
  "name": "photo.jpg",
  "contentType": "image/jpeg",
  "originProperties": {
    "source": "android",
    "flow": "inspection"
  }
}
```

## `GET /import`

Purpose:

- return upload URL or upload data used by import workflows

## `GET /export`

Purpose:

- trigger readings export through the Meters-Data Lambda flow

Common query options:

- `meterId`
- `startTime`
- `endTime`

Alternative offset/time-window mode is also supported by the underlying implementation.

## Related endpoint

- `POST /files/attach/device/{id}` is documented in [Data Sources and Device APIs](/developers/api-reference/data-sources-and-devices)


Reference the file lookup, signed-upload, import, and export endpoints used by SDK-driven file and reading flows.

Browse Guides

Generate an API Key

Create the key from the UI

Important notes

Suggested usage

More developer docs

Files, Uploads, and Export

Get File