Files and folders

Files are the basic unit of context in Orcha. Each file has a type (markdown, json, yaml, or text), lives in a folder or at the workspace root, and is indexed for retrieval automatically.

Folders

Folders nest to any depth. Moving a file between folders does not change its ID, so agent references and citations stay stable. Folder IDs also drive token scoping: a folder-scoped token sees a folder and everything under it.

Trash and recovery

Deleting a file or folder is a soft delete: it moves to the Trash page, where it can be restored. Deleting a folder moves its contents with it. The REST DELETE endpoints and the MCP delete_file tool behave the same way.

Working with files from agents

• List files with GET /api/v1/files or the list_files MCP tool, optionally filtered by folderId.
• Read a file with GET /api/v1/files/:id, or GET /api/v1/files/:id/raw for the raw content with a proper Content-Type header.
• For large files over MCP, get_file accepts fromLine and maxLines so agents can read only the relevant range. Search results include startLine anchors to jump from.
• get_files fetches up to 20 files in one MCP call.

The full endpoint list is in the API reference; the tool list is in the MCP reference.