> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usepatchwork.co/llms.txt
> Use this file to discover all available pages before exploring further.

# The File object

> A stored file — bytes plus metadata — referenced by a durable handle.

Upload a file and you get this object back. Reference its `id` (`file_…`) wherever a product accepts a file. `size` and `sha256` are set once the file is `ready`; while `uploading`, the object carries the resumable session's `segment_size` and `received_segments` instead.

```json theme={null}
{
  "id": "file_9f3a...",
  "state": "ready",
  "media_type": "application/pdf",
  "filename": "invoice.pdf",
  "size": 48213,
  "sha256": "e3b0c442...",
  "expires_at": "2026-09-03T18:22:00Z",
  "created_at": "2026-09-02T18:22:00Z"
}
```

An upload in progress:

```json theme={null}
{
  "id": "file_9f3a...",
  "state": "uploading",
  "media_type": "application/pdf",
  "filename": "big-scan.pdf",
  "segment_size": 5242880,
  "received_segments": [0, 1, 3],
  "expires_at": "2026-09-03T18:22:00Z",
  "created_at": "2026-09-02T18:22:00Z"
}
```

## Attributes

<ResponseField name="id" type="string" required>
  File handle (`file_…`). Reference this wherever a product takes a file.
</ResponseField>

<ResponseField name="state" type="enum" required>
  One of `uploading`, `ready`, `referenced`, or `expired`. A referenced file is pinned from cleanup.
</ResponseField>

<ResponseField name="media_type" type="string">
  MIME type, as declared on upload.
</ResponseField>

<ResponseField name="filename" type="string">
  Optional client-supplied name. Never used to infer content type.
</ResponseField>

<ResponseField name="size" type="integer">
  Byte size. Present once `ready`.
</ResponseField>

<ResponseField name="sha256" type="string">
  Whole-file SHA-256. Present once `ready`.
</ResponseField>

<ResponseField name="segment_size" type="integer">
  Bytes per segment for a chunked upload. Present while `uploading`.
</ResponseField>

<ResponseField name="received_segments" type="array">
  Zero-based indices received so far. Present while `uploading` — resume by sending the ones missing.
</ResponseField>

<ResponseField name="expires_at" type="string">
  When the file is swept if nothing references it. A reference suspends this.
</ResponseField>

<ResponseField name="created_at" type="string">
  When the file was created.
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.