Files and folders

Files are the basic unit of context in Orcha. Each file has a type: markdown, json, yaml, or text. A file is in a folder or at the workspace root. Orcha indexes each file for retrieval automatically.

Folders

You can put folders in folders to all depths. When you move a file to a different folder, its ID does not change. Thus, agent references and citations stay stable. Folder IDs also control token scoping. A folder-scoped token can see a folder and all content below it.

Trash and recovery

A delete of a file or folder is a soft delete. Orcha moves the item to the Trash page, where you can restore it. When you delete a folder, Orcha also moves its contents to the trash. The REST DELETE endpoints and the MCP delete_file tool operate in the same way.

Working with files from agents

• To list files, use GET /api/v1/files or the list_files MCP tool. You can filter by folderId.
• To read a file, use GET /api/v1/files/:id. To get the raw content with a correct Content-Type header, use GET /api/v1/files/:id/raw.
• For large files over MCP, get_file accepts fromLine and maxLines. Thus, agents can read only the necessary range. Search results include startLine anchors that agents can use as a start point.
• get_files gets up to 20 files in one MCP call.

The API reference lists all endpoints. The MCP reference lists all tools.