BetaServer tools are currently in beta. The API and behavior may change.
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.
Quick Start
Configuration
The files tool has no configuration options — which workspace and files it can access is determined by your API key and thex-openrouter-file-ids header, so enabling the tool takes only its type:
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 is currently no separate charge for the files tool; you pay only for standard token usage.Next Steps
- Server Tools Overview — Learn about server tools
- Apply Patch — Let models propose file edits as V4A diffs
- Tool Calling — Learn about user-defined tool calling