> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cogniagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Workspace files from your AI tools
> Let Claude, Cursor or any MCP client list, search, read, upload, move and trash Workspace files, acting as you.
Ask Claude, Cursor or any AI tool connected to your workspace to read a report, file a document or tidy a folder in Workspace files, and it does it as you, in the same folder your team and coworkers use.
## Before you start
Connect your AI tool to your workspace first: [Connect MCP](/mcp-server) walks through creating a **workspace API key** and pasting the setup into your tool.
* **It acts as a person.** Every change is made as the person who created the workspace API key, and shows on the Files page under their name. It works only while that person is an active member of the workspace; if they leave, a current member creates a new key.
* **It sees what that person sees.** The whole of [Workspace files](/cowork/files/workspace-files), and nothing in anyone's tasks.
* **Your tool can learn the rules itself.** Ask it to read the `workspace_files` guide (`read_mcp_guide`) before it starts: paths, mentions, limits and what to do on a conflict.
```mermaid theme={null}
flowchart LR
T["Your AI tool"] -->|workspace API key| W["Workspace files"]
W -->|"Modified by: the key's creator"| F["The Files page"]
W --> C["Coworkers, at files/"]
W --> R["Workflows"]
```
## What your AI can do
| Tool | What it does |
| - | - |
| `list_workspace_files` | Lists one folder, folders first, a page at a time. |
| `search_workspace_files` | Finds files and folders by name, anywhere or under a `folder`, and filters by `kind`, `mimeTypes`, who changed them last (`updatedByType`, `updatedById`) and when (`modifiedAfter`, `modifiedBefore`). |
| `read_workspace_file` | Reads a text file, or downloads any other file up to 5 MB. |
| `write_workspace_file` | Uploads `text` or a file in `base64`, up to 10 MB, creating any missing folders. |
| `create_workspace_folder` | Makes a folder, with any missing parents. An existing one is reused. |
| `move_workspace_file` | Renames a file or folder, moves it with `toFolder`, or both. |
| `trash_workspace_file` | Moves a file or folder to the Trash. |
## Naming files
A file is named by its path from the top of the folder: `Reports/2026/Q3 summary.md`. Your tool can also write it as `files/Reports/2026/Q3 summary.md` or `@files/Reports/2026/Q3 summary.md`, the way chat messages and coworkers name files. Every result carries a `mention` to paste into a message for a person or a coworker.
* **Names are case-insensitive.** `Report.pdf` and `report.PDF` can't both live in one folder. Results spell a path the way it's really stored.
* **An id outlives a rename.** Any tool that takes `path` also takes `nodeId`, the `id` from a result. A path names whatever holds that name now; an id keeps naming the same file after someone renames or moves it.
## Reading and downloading
* **Text** comes back as text, up to 50,000 characters a call by default and 200,000 at most (`maxChars`). A longer file is read in slices: the result says `hasMore`, and your tool asks again from `nextOffset` with the same `versionId`, so every slice comes from the same version.
* **Any other file** up to 5 MB comes back as a download. A bigger one returns its details only; open it on the Files page.
* **Search finds names, not contents.** To find a file by what it says, your tool searches for likely names, then reads the candidates.
## Uploading and replacing
When the name is taken, `write_workspace_file` refuses by default. `ifExists` decides:
| `ifExists` | What happens |
| - | - |
| `fail` (default) | Nothing is written; the result says the name is taken. |
| `keep_both` | Written beside it under a free name, like `report (1).pdf`. |
| `replace` | Written as a new version of that file. |
To replace safely, read first and pass the `revision` it returned as `ifMatch`. If someone changed the file in between, the write is refused with a `conflict` instead of overwriting their work; your tool reads again and decides. `note`, one line of up to 500 characters, shows in the file's history.
## Versions
Your tool's saves to one file within 10 minutes join one version, so a tool fixing a report in several passes leaves one version, not ten.
Because the tool acts as a person, a `replace` takes one of the file's three version places like your own save would, and can push out the oldest version, whoever wrote it. Before an AI tool rewrites a file you can't lose, make it a [checkpoint](/cowork/files/editing-and-history#keep-a-version-for-good-checkpoints) on the Files page, or ask the tool to write beside it with `keep_both`. Your tool can't make or remove checkpoints itself.
## The Trash, not delete
There's no permanent delete from an AI tool. `trash_workspace_file` moves a file or a whole folder to the Trash, where anyone can restore it for 30 days. Ask your tool to tell you what it trashed.
## Try these
> *"Read Reports/2026/Q3 summary.md in Workspace files and save a one-page version beside it as Q3 summary short.md."*
> *"Find every invoice PDF changed this week in Workspace files and move them into Inbox/Invoices."*
> *"List what's in the Contracts folder and tell me which files Sam changed last."*
## Common questions
The name of the person who created the workspace API key it uses. On the Files page, Modified by and Activity show that person.
No. It can only move them to the Trash, where they can be restored for 30 days.
Either the name is taken and `ifExists` was `fail`, someone changed the file after your tool read it, or the workspace's storage is full. The result says which. For storage, move files nobody needs to the Trash.
It downloads them, up to 5 MB, and your AI tool reads them its own way. Text files come back as text.
## Next steps
Set up your AI tool and its workspace API key.
The shared folder at a glance.
Versions and checkpoints on the Files page.
See what your AI tool changed.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.