Files Server Tool - Workspace File Access for Any Model

Beta

BetaServer tools are currently in beta. The API and behavior may change.

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.

Requires the file-ids headerThe files tool requires the x-openrouter-file-ids: openrouter request header and an authenticated workspace. Without the header, tool calls return an error to the model.

Quick Start

Configuration

The files tool has no configuration options — which workspace and files it can access is determined by your API key and the x-openrouter-file-ids header, 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 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

Overview

Models & Routing

Features

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