composiohq--composio/ts/docs/api/tool-router-files.md

Tool Router Session Files

Tool Router sessions include a virtual filesystem mount that enables file storage and retrieval within a session. This is useful for agent workflows, document processing, and tools that need to read or write files. Access the files API via session.experimental.files on any Tool Router session.

Related:

• Tool Router – Session creation, configuration, and session.experimental.files overview
• Auto Upload and Download – File handling during tool execution (different feature)

Overview

Each Tool Router session has a files property that provides:

• List – Browse files and directories with cursor-based pagination
• Upload – Upload files from paths, URLs, native File objects, or raw buffers
• Download – Get presigned download URLs and RemoteFile instances
• Delete – Remove files or directories from the mount

Files are stored in a virtual filesystem attached to the session. Tools executing in the session can access these files (e.g., at /mnt/files/ inside the sandbox). The mount ID defaults to "files" and can be overridden when using custom mounts.

Quick Start

import { Composio } from '@composio/core';

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
const session = await composio.create('default');

// Upload a file
const file = await session.experimental.files.upload('/path/to/report.pdf');
console.log('Uploaded:', file.mountRelativePath);

// List files
const { items, nextCursor } = await session.experimental.files.list({ path: '/' });

// Download a file
const remoteFile = await session.experimental.files.download('report.pdf');
const buffer = await remoteFile.buffer();
await remoteFile.save('/tmp/report.pdf');

List Files

List files and directories at a path on the session's file mount. Supports cursor-based pagination.

Method Signature

session.experimental.files.list(options?: ToolRouterSessionFilesMountListOptions): Promise<FileListResponse>

Options

Option	Type	Default	Description
path	string	-	Directory path to list. Use "/" for root.
mountId	string	"files"	The file mount ID.
cursor	string	-	Pagination cursor from the previous response's nextCursor.
limit	number	-	Max files per page (1–500).

Response

interface FileListResponse {
  items: Array<{
    lastModified: string;      // ISO 8601 timestamp
    mountRelativePath: string; // e.g. "report.pdf"
    sandboxMountPrefix: string; // e.g. "/mnt/files"
    size: number;             // File size in bytes
  }>;
  nextCursor?: string;        // Present when more pages exist
}

Examples

// List root directory
const { items } = await session.experimental.files.list({ path: '/' });

// List a subdirectory
const { items } = await session.experimental.files.list({ path: '/documents' });

// Paginated listing
let result = await session.experimental.files.list({ path: '/', limit: 10 });
while (result.nextCursor) {
  result = await session.experimental.files.list({
    path: '/',
    cursor: result.nextCursor,
    limit: 10,
  });
}

Upload Files

Upload files to the session's mount. Accepts multiple input types: file paths (local or URL), native File objects, or raw buffers (ArrayBuffer | Uint8Array).

Method Signature

session.experimental.files.upload(
  input: string | File | ArrayBuffer | Uint8Array,
  options?: ToolRouterSessionFilesMountUploadOptions
): Promise<RemoteFile>

Input Types

Input Type	Description	Example
string	Local path or HTTP(S) URL	'/path/to/file.pdf', 'https://example.com/file.pdf'
File	Native browser/Node File	inputElement.files[0]
ArrayBuffer	Raw binary buffer	await file.arrayBuffer()
Uint8Array	Typed array buffer	new TextEncoder().encode('hello')

Upload Options

Option	Type	Default	Description
remotePath	string	-	Remote path/filename on the mount. Required when passing a buffer (provides filename; mimetype defaults to application/octet-stream).
mountId	string	"files"	The file mount ID.
mimetype	string	-	MIME type. Required when passing a buffer unless remotePath is provided. Ignored when passing File (uses file.type).

How It Works

1. Path (string) – If the path starts with http:// or https://, the file is fetched from the URL. Otherwise it is read from the local filesystem. The filename is derived from the path or URL.
2. File – Used directly. Filename comes from file.name unless remotePath is provided.
3. Buffer – Wrapped in a File object. Either mimetype or remotePath must be provided. If only remotePath is given, mimetype defaults to application/octet-stream. If only mimetype is given, a filename is generated from the extension (upload-{id}.{ext}).

Examples

// From local path
const file = await session.experimental.files.upload('/path/to/report.pdf');

// From URL
const file = await session.experimental.files.upload('https://example.com/document.pdf');

// From native File (e.g. file input)
const file = await session.experimental.files.upload(fileInput.files[0]);

// From buffer with explicit path and mimetype
const buffer = new TextEncoder().encode('{"key": "value"}');
const file = await session.experimental.files.upload(buffer, {
  remotePath: 'data.json',
  mimetype: 'application/json',
});

// From buffer – mimetype or remotePath required
const pngBytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, ...]);
const file = await session.experimental.files.upload(pngBytes, {
  remotePath: 'screenshot.png',
  mimetype: 'image/png',
});

Download Files

Get a RemoteFile for a file on the mount. The RemoteFile provides a presigned download URL and methods to fetch content.

Method Signature

session.experimental.files.download(
  filePath: string,
  options?: ToolRouterSessionFilesMountDownloadOptions
): Promise<RemoteFile>

Parameters

• filePath – Path of the file on the mount (e.g. "report.pdf", "output/data.csv").
• options.mountId – Mount ID (default: "files").

RemoteFile

The returned RemoteFile has:

Property	Type	Description
expiresAt	string	ISO 8601 when the download URL expires
mountRelativePath	string	Path within the mount
sandboxMountPrefix	string	Absolute mount path (e.g. /mnt/files)
downloadUrl	string	Presigned URL for downloading
filename	string	Basename of the path

Methods:

• buffer() – Fetch content as Uint8Array
• text() – Fetch content as UTF-8 string
• blob() – Fetch content as Blob
• save(path?) – Download and save to disk (Node.js only; path defaults to ~/.composio/files/)

Examples

const remoteFile = await session.experimental.files.download('/output/report.pdf');

// Fetch content
const buffer = await remoteFile.buffer();
const text = await remoteFile.text();

// Save to disk (Node.js)
await remoteFile.save('/tmp/report.pdf');
await remoteFile.save(); // Uses ~/.composio/files/{filename}

Delete Files

Delete a file or directory from the mount.

Method Signature

session.experimental.files.delete(
  remotePath: string,
  options?: ToolRouterSessionFilesMountDeleteOptions
): Promise<FileDeleteResponse>

Examples

await session.experimental.files.delete('/temp/cache.json');
await session.experimental.files.delete('/old-backup', { mountId: 'custom-mount' });

Type Reference

ToolRouterSessionFilesMountListOptions

interface ToolRouterSessionFilesMountListOptions {
  path?: string;
  mountId?: string;   // default: "files"
  cursor?: string;
  limit?: number;     // 1-500
}

ToolRouterSessionFilesMountUploadOptions

interface ToolRouterSessionFilesMountUploadOptions {
  remotePath?: string;
  mountId?: string;   // default: "files"
  mimetype?: string;
}

FileListResponse

interface FileListResponse {
  items: Array<{
    lastModified: string;
    mountRelativePath: string;
    sandboxMountPrefix: string;
    size: number;
  }>;
  nextCursor?: string;
}

RemoteFile (from download/upload)

interface RemoteFile {
  readonly expiresAt: string;
  readonly mountRelativePath: string;
  readonly sandboxMountPrefix: string;
  readonly downloadUrl: string;
  readonly filename: string;

  buffer(): Promise<Uint8Array>;
  text(): Promise<string>;
  blob(): Promise<Blob>;
  save(path?: string): Promise<string>;  // Node.js only
}

Exports

The following are exported from @composio/core:

• FileListResponse – List response type
• ToolRouterSessionFilesMountListOptions – List options type
• RemoteFile – File class with buffer, text, blob, save
• getExtensionFromMimeType – Map MIME type to file extension

Platform Support

• Node.js – Full support (paths, save()).
• Bun – Full support.
• Browser – Paths and save() are limited; use File or buffers.
• Cloudflare Workers / Edge – No filesystem; use File or buffers only.