---
title: "File"
description: "File — unified content entity. Every piece of user content (document,
image, video, anything) is a file row. Image and video specializations
live in side tables and are surfaced via the filtered image/video
convenience endpoints.

Multipart upload state is inline on the file row (`r2MultipartId`,
`parts`, etc.) and null once `status = \"ready\"`."
section: "Reference"
group: "Types"
order: 89
---

## Definition

```ts
interface File {
  id: string;
  workspaceId: string;
  directoryId: string;
  name: string;
  mime: string | null;
  size: number | null;
  status: "error" | "ready" | "uploading";
  errorMessage: string | null;
  metadata: any;
  createdBy: string | null;
  createdAt: string;
  updatedAt: string;
  finalizedAt: string | null;
  expiresAt: string | null;
}
```

## Fields

| Field          | Type                                | Notes                                                                                                                                           |
| -------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | `string`                            | `readonly` `required`                                                                                                                           |
| `workspaceId`  | `string`                            | `required` — Workspace that owns this file.                                                                                                     |
| `directoryId`  | `string`                            | `required` — Directory containing this file in the DB hierarchy.                                                                                |
| `name`         | `string`                            | `required` — Filename as shown to the user.                                                                                                     |
| `mime`         | `string \| null`                    | `required` — Verified MIME type of the file; null until the upload is finalized.                                                                |
| `size`         | `number \| null`                    | `required` — File size in bytes; null until the upload is finalized.                                                                            |
| `status`       | `"error" \| "ready" \| "uploading"` | `required` — Lifecycle state: 'uploading', 'ready', or 'error'.                                                                                 |
| `errorMessage` | `string \| null`                    | `required` — Error message when status is 'error', otherwise null.                                                                              |
| `metadata`     | `any`                               | `required` — Free-form metadata (EXIF, duration, dimensions, etc.).                                                                             |
| `createdBy`    | `string \| null`                    | `required` — User who created the file; null for system-generated files.                                                                        |
| `createdAt`    | `string`                            | `readonly` `required` — ISO-8601 timestamp of creation.                                                                                         |
| `updatedAt`    | `string`                            | `readonly` `required` — ISO-8601 timestamp of the last update.                                                                                  |
| `finalizedAt`  | `string \| null`                    | `required` — ISO-8601 timestamp when the upload was completed.                                                                                  |
| `expiresAt`    | `string \| null`                    | `required` — Optional TTL. Once past this timestamp the file (DB row + R2 object) is garbage-collected by the cleanup worker. Null = permanent. |