Files Server Tool - Workspace File Access for Any Model

Beta

BetaServer tools are currently in beta. The API and behavior may change.The files tool and the Files API are available on the global endpoint (openrouter.ai) only. Requests through the in-region endpoints (eu.openrouter.ai, us.openrouter.ai) are rejected; the Files API returns a 403 there.

The openrouter:files server tool lets a model read, write, edit, and list text files in your workspace via the OpenRouter Files API. When the model needs file access (reading an uploaded document, saving output, or applying a targeted edit), it calls the tool and OpenRouter executes the operation server-side.

The tool sees one workspace: your key’sThe files it can list, read, write, and edit are the ones in the workspace your API key is scoped to. A key with no workspace gets your default workspace, not necessarily the one you uploaded through in the dashboard. If the model reports a file it should be able to see as missing, check which workspace the key belongs to first.

Quick start

Configuration

The files tool has no configuration options. Which workspace and files it can access is determined by your API key, so enabling the tool takes only its type:

{
  "type": "openrouter:files"
}

Operations

The model generates the call arguments. Each call performs one operation:

Operation	Description
`list`	List workspace files, optionally filtered by `filename_filter`
`read`	Read a file by `file_id` or `filename`
`write`	Create a new file from `filename` and `content`
`edit`	Replace `old_string` with `new_string` in a file

Call arguments

Field	Type	Description
`operation`	string	The file operation to perform: `list`, `read`, `write`, or `edit`
`file_id`	string	Target file id (read/edit). Preferred over `filename` when known
`filename`	string	Target filename (read/edit lookup), or the filename for a new file (write). May include a folder path
`filename_filter`	string	list: only return files whose filename contains this substring
`content`	string	write: the full UTF-8 text content of the new file
`old_string`	string	edit: the exact text to replace (must match a single location)
`new_string`	string	edit: the replacement text
`new_filename`	string	edit: optional filename for the edited copy; defaults to the source filename

Edits are copy-on-writeEditing a file creates a new copy with a new file_id; the original file is left unchanged.

Response

The tool returns { "result": ... } on success with the operation’s output (file listing, file content, or the new file’s metadata), or { "error": "..." } when the operation fails (for example, when a required field is missing or the target file isn’t found). The model reads the error and can retry with corrected arguments.

Pricing

There’s currently no separate charge for the files tool; you pay only for standard token usage.

Next steps

Server Tools Overview: Learn about server tools
Files API: Upload and manage workspace files
Containers: How sandbox containers work
Apply Patch: Let models propose file edits as V4A diffs
Tool Calling: Learn about user-defined tool calling

Overview

Models & Routing

Tool Calling

Features

Ori

Privacy

Best Practices

Community

Files

Quick start

Configuration

Operations

Call arguments

Response

Pricing

Next steps

​Quick start

​Configuration

​Operations

​Call arguments

​Response

​Pricing

​Next steps

Quick start

Configuration

Operations

Call arguments

Response

Pricing

Next steps