File Uploads

The Client SDK supports uploading images and documents that can be sent with messages. This enables vision model capabilities (analyzing images) and document processing.

Overview

File uploads follow a two-step flow:

Request upload URLs from the platform via your backend
Upload files directly to S3 using presigned URLs
Send file references with your message

This architecture keeps your API key secure on the server while enabling fast, direct uploads.

Setup

Backend: Upload URLs Endpoint

Create an endpoint that proxies upload URL requests to the Octavus platform:

typescript

Client: Configure File Uploads

Pass requestUploadUrls to the chat hook:

tsx

Uploading Files

Method 1: Upload Before Sending

For the best UX (showing upload progress), upload files first, then send:

tsx

Method 2: Upload on Send (Automatic)

For simpler implementations, pass File objects directly:

tsx

The SDK automatically uploads the files before sending. Note: This doesn't provide upload progress.

FileReference Type

File references contain metadata and URLs:

typescript

Protocol Integration

To accept files in your agent protocol, use the file[] type:

yaml

The file type is a built-in type representing uploaded files. Use file[] for arrays of files.

Supported File Types

Type	Media Types
Images	`image/jpeg`, `image/png`, `image/gif`, `image/webp`
Documents	`application/pdf`, `text/plain`, `text/markdown`, `application/json`

File Limits

Limit	Value
Max file size	10 MB
Max total per request	50 MB
Max files per request	20
Upload URL expiry	15 minutes
Download URL expiry	24 hours

Rendering User Files

User-uploaded files appear as UIFilePart in user messages:

tsx

Server SDK: Files API

The Server SDK provides direct access to the Files API:

typescript

Complete Example

Here's a full chat input component with file upload:

tsx