# Upload a file

Upload a file to the caller's storage. The body is
`multipart/form-data` with a required `file` field and optional
`purpose` label.

The upload is streamed straight into object storage (no gateway
buffering). Hard cap: 500 MB per file. Any MIME is accepted;
the server classifies the row as `image`, `video`, `audio`, or
`file` based on the Content-Type.

Uploads count against the account's 5 GB storage quota.
Overages still upload successfully but are retained only 24 h.

## POST /v1/files

> Upload a file

Upload a file to the caller's storage. The body is
`multipart/form-data` with a required `file` field and optional
`purpose` label.

The upload is streamed straight into object storage (no gateway
buffering). Hard cap: 500 MB per file. Any MIME is accepted;
the server classifies the row as `image`, `video`, `audio`, or
`file` based on the Content-Type.

Uploads count against the account's 5 GB storage quota.
Overages still upload successfully but are retained only 24 h.

### Authentication

`Authorization: Bearer tr-xxx`

### Request Body

Content-Type: `multipart/form-data`

- **file** `string` **(required)**  
  File content
- **purpose** `string`  
  Optional label echoed back on the response

### Error Codes

- `201`: Upload succeeded
- `400`: 
- `401`: 
- `413`: File exceeds the 500 MB limit
- `503`: This deployment is not configured for uploads