# Get File

Source: https://help.zira.us/developers/api-reference/get-file
Summary: Fetch one file by ID, with a ready-to-use download URL.
Updated: 2026-08-06

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