FeaturesServer Tools

Files

Beta
Let any model read, write, edit, and list your workspace files
Beta

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

The openrouter:files server tool lets any model read, write, edit, and list the files stored in your OpenRouter workspace through the Files API. The model decides when to call it; OpenRouter executes the operation server-side against your workspace and returns the result.

Enabling the tool

The files tool operates on OpenRouter-hosted files, so it is only active when the request opts into OpenRouter file handling via the x-openrouter-file-ids header:

x-openrouter-file-ids: openrouter

Without this header (or with x-openrouter-file-ids: provider, the current default), the tool is inert: the model is told that files are unavailable. This is the same header that controls whether file_id message references are resolved by OpenRouter or passed through to the upstream provider.

Quick Start

1const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
2  method: 'POST',
3  headers: {
4    Authorization: 'Bearer {{API_KEY_REF}}',
5    'Content-Type': 'application/json',
6    'x-openrouter-file-ids': 'openrouter',
7  },
8  body: JSON.stringify({
9    model: '{{MODEL}}',
10    messages: [
11      {
12        role: 'user',
13        content: 'List my files, then create notes.txt with a summary.'
14      }
15    ],
16    tools: [
17      { type: 'openrouter:files' }
18    ]
19  }),
20});
21
22const data = await response.json();
23console.log(data.choices[0].message.content);

Operations

The model selects an operation via the operation argument:

OperationDescription
listList the workspace’s files (optionally filtered by filename substring)
readRead a file’s text content by file_id or filename
writeCreate a new text file from a filename and content
editReplace a string in a file, writing the result to a new file

Edit creates a new file

Editing is copy-on-write: an edit reads the source file, applies the string replacement, and writes the result as a new file with a new file_id. The original file is left unchanged, so existing references keep resolving. The response includes the new file_id and the source_file_id it was derived from.

Constraints

  • Text only. The tool reads and writes UTF-8 text files. Binary files are rejected.
  • Size limit. Individual reads and writes are capped at 20 MB.
  • Workspace-scoped. All operations run against the workspace of the authenticated request. Anonymous (unauthenticated) callers have no workspace, so the tool is unavailable.
  • documents/ namespace. Files live under your workspace’s default document namespace — the same files surfaced in the Files dashboard.

Pricing

The files tool has no additional cost beyond standard token usage. Stored files count toward your workspace storage quota.

Next Steps