File System

Each thread has isolated file storage accessible via these endpoints. Files are stored in the thread’s SQLite database with support for external references (URLs, S3, R2).

List Directory / Query Files

threadId

string

required

The thread identifier

stats

boolean

Return storage statistics instead of file list

grep

string

Full-text search pattern

find

string

Glob pattern for path matching (e.g., *.jpg)

# List root directory
GET /api/threads/{threadId}/fs

# Get storage stats
GET /api/threads/{threadId}/fs?stats=1

# Full-text search
GET /api/threads/{threadId}/fs?grep=searchterm

# Find by pattern
GET /api/threads/{threadId}/fs?find=*.jpg

{
  "files": [
    {
      "path": "/attachments/photo.jpg",
      "name": "photo.jpg",
      "mimeType": "image/jpeg",
      "storage": "local",
      "size": 245123,
      "isDirectory": false,
      "createdAt": 1704067200000,
      "width": 2048,
      "height": 1536
    }
  ],
  "path": "/"
}

{
  "totalSize": 5242880,
  "fileCount": 12
}

Get File

threadId

string

required

The thread identifier

path

string

required

File path (e.g., attachments/photo.jpg)

thumbnail

boolean

Return image thumbnail instead of full file

format

string

Set to json to return metadata only

# Get file content
GET /api/threads/{threadId}/fs/{path}

# Get thumbnail
GET /api/threads/{threadId}/fs/{path}?thumbnail=1

# Get metadata only
GET /api/threads/{threadId}/fs/{path}?format=json

Returns binary file data with appropriate Content-Type header, or JSON metadata when format=json.

Write File

threadId

string

required

The thread identifier

path

string

required

File path to write

data

string

Base64-encoded file data

mimeType

string

MIME type of the file

metadata

object

Optional custom metadata

width

number

Image width in pixels (for images)

height

number

Image height in pixels (for images)

thumbnail

string

Base64-encoded thumbnail for images

type

string

Set to "directory" to create a directory

location

string

External URL for linked files (instead of data)

# Write file (JSON)
POST /api/threads/{threadId}/fs/{path}
Content-Type: application/json
{
  "data": "base64...",
  "mimeType": "image/jpeg"
}

# Create directory
POST /api/threads/{threadId}/fs/{path}
Content-Type: application/json
{ "type": "directory" }

# Link external file
POST /api/threads/{threadId}/fs/{path}
Content-Type: application/json
{
  "location": "https://example.com/file.pdf",
  "mimeType": "application/pdf",
  "size": 1024000
}

# Raw binary upload (auto-chunks large files)
POST /api/threads/{threadId}/fs/{path}
Content-Type: application/octet-stream
[binary data]

Large files (>1.75MB) are automatically chunked server-side. No special client handling is required—just send a normal POST request with the binary data.

{
  "id": "/attachments/photo.jpg",
  "type": "file",
  "path": "/attachments/photo.jpg",
  "name": "photo.jpg",
  "mimeType": "image/jpeg",
  "size": 245123,
  "width": 2048,
  "height": 1536
}

Delete File

threadId

string

required

The thread identifier

path

string

required

File or directory path to delete

DELETE /api/threads/{threadId}/fs/{path}

Returns 204 No Content on success. Directories must be empty to delete.

FileRecord Schema

interface FileRecord {
  path: string;           // Full path (e.g., "/attachments/photo.jpg")
  name: string;           // Filename
  mimeType: string;       // MIME type
  storage: 'local' | 'url' | 's3' | 'r2';
  location?: string;      // External URL (if storage !== 'local')
  size: number;           // Size in bytes
  metadata?: object;      // Custom metadata
  isDirectory: boolean;
  createdAt: number;      // Unix timestamp (ms)
  width?: number;         // Image width in pixels (images only)
  height?: number;        // Image height in pixels (images only)
  isChunked?: boolean;    // True if file is stored in chunks (>1.75MB)
  chunkCount?: number;    // Number of chunks (if chunked)
}

Threads

Messages

Define Utilities

WebSocket

File System

List Directory / Query Files

Get File

Write File

Delete File

FileRecord Schema

​List Directory / Query Files

​Get File

​Write File

​Delete File

​FileRecord Schema

List Directory / Query Files

Get File

Write File

Delete File

FileRecord Schema