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 you have a file ID and need its metadata plus a URL you can download from directly.

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

fileId

Defaults to true. Set it to `false` to get the metadata without generating a download URL — the `file` field then comes back empty.

resolveFiles

Northwind Manufacturing

line-1-inspection.png

Fresno Plant

data.id

data.name

File extension, e.g. `png`, `pdf`, `csv`.

data.fileType

data.fileSize

When the file was created, with a UTC offset.

data.createdDate

ID of the user who uploaded it. A number here, unlike most IDs in this API.

data.createdBy

data.company

data.site

Set instead of `company`/`site` when the file belongs to a conversation.

data.conversation

Where the file came from, when Zira recorded it.

data.origin

The metadata you passed as `originProperties` when the upload was created — useful for matching a file back to your own record.

data.originProperties

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

data.file

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.

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

Get File


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



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

Create Signed Upload


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.

https://api.zira.us/public/files/{fileId}

Description