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

# File System

> How ModelRoute handles file uploads and downloads securely.

## Why files?

ModelRoute acts as a secure intermediary between you and AI providers. When you upload a file:

1. **Your file stays on ModelRoute** -- providers never receive your original file URL or storage credentials
2. **ModelRoute transfers the file** to the provider using provider-specific mechanisms
3. **Output files are stored on ModelRoute** -- you download them via ModelRoute, not from the provider

This design ensures provider isolation. Switching providers or adding new ones never requires changes to your file handling code.

## Zero-trust security

ModelRoute never trusts client-provided metadata. When you upload a file:

* **Content type** is detected server-side from file magic bytes
* **Filename** is replaced with a UUID -- original filenames are never stored
* **File size** is measured from the actual uploaded bytes in storage
* **Uploads are streamed** -- the server never holds the full file in memory

You send raw bytes. ModelRoute handles everything else.

## File references

Every uploaded file gets a unique reference in the format:

```
file_<uuid>
```

Example: `file_f47ac10b-58cc-4372-a567-0e02b2c3d479`

Use file references in execution inputs (e.g., an image to transform) and read them from execution outputs (e.g., a generated image).

## Limits

| Limit                   | Value                                              |
| ----------------------- | -------------------------------------------------- |
| Maximum file size       | 150 MB                                             |
| Supported upload method | Presigned URL (PUT)                                |
| Default TTL             | Configurable per-organization (1-365 days)         |
| File access             | Scoped to your organization -- no cross-org access |

## File lifecycle

```mermaid theme={null}
flowchart LR
    A[Request presigned URL] --> B[Upload via PUT]
    B --> C[Confirm upload]
    C --> D[File active]
    D --> E[Use in execution input]
    D --> F[Download anytime]
    D --> G[Auto-expire via TTL]
```

1. **Request a presigned upload URL** -- `POST /v1/files/upload`
2. **Upload via HTTP PUT** to the presigned URL (raw bytes, no metadata)
3. **Confirm the upload** -- `POST /v1/files/confirm`
4. **Use the file reference** in execution inputs
5. **Download results** -- execution outputs contain file references you can download
6. **Files auto-expire** based on your organization's TTL settings

## Audit trail

Every upload and delete is tracked with full attribution:

* **Who** -- API key ID or console user ID
* **When** -- timestamp of the action
* **From where** -- IP address of the request

View the complete activity log in the Storage (CDN) page of your dashboard.

## Next steps

<CardGroup cols={3}>
  <Card title="Uploading Files" icon="upload" href="/files/uploading">
    Step-by-step guide to uploading files.
  </Card>

  <Card title="Downloading Files" icon="download" href="/files/downloading">
    How to download execution results.
  </Card>

  <Card title="Storage Pricing" icon="dollar-sign" href="/files/pricing">
    \$0.05/GB/month. Uploads, downloads, and egress are free.
  </Card>
</CardGroup>