Storage

Support reference for the org Storage page (`/storage`) and the org storage APIs behind it.

For the organization private API surface under `/api/private`, see `private-api.md`.

- Browse folders with URL-backed navigation via `?path=...`. - Switch between list and grid views. - Search the current folder, sort, hide/show columns, and filter by file type and modified date. - Select multiple items and bulk delete. - Create folders. - Upload by file picker, drag-and-drop, or folder upload. - Download files. - Copy file or folder paths. - Share folders with AI teammates. - Open non-folder items in Cowork via `/cowork?path=...`.

- Files: `Download`, `Copy Path`, `Delete`. - Folders: `Share`, `Copy Path`, `Delete`. - The Storage UI does not currently expose rename, copy, or move actions, even though org APIs exist for them. - The code still contains an unused details panel, but `/storage` does not currently expose a working details action.

- Allowed upload types: `png`, `jpg`, `jpeg`, `gif`, `webp`, `svg`, `pdf`, `docx`, `xlsx`, `pptx`, `txt`, `htm`, `html`, `md`, `csv`, `json`, `yaml`, `yml`. - Max upload size: `10 MB` per file. - In the `/storage` UI, individual files cannot be uploaded to root (`/`). - The org and private upload APIs still allow root uploads when `path` is omitted. - Root-level folder uploads are allowed. - Duplicate handling offers `Skip existing` and `Replace`. - Upload UI supports pause, resume, retry, cancel, and persistent progress.

- Only folders can be shared. - Root (`/`) cannot be shared. - Sharing uses a dedicated dialog with AI teammates in the org, but Ally is not presented as a normal editable row there. - The dialog always shows an `Ally` row with both `Read` and `Write` checked and disabled. - The dialog text for Ally says `Full storage access is automatic.` - Ally is the only special system-backed teammate in this share list. - Permissions are `read` and `write`. - In the current dialog, enabling `write` also enables `read`. - If `write` is removed, `read` remains checked unless it is inherited from a parent share. - `read` is disabled when it is inherited or when `write` is checked, so the dialog never allows write-only access. - Parent-folder permissions appear as inherited (`from_parent: true`) and cannot be toggled from the child folder. - Deleting a folder or file path removes matching share records for that path and nested paths.

- Storage rows can show indexing states: `Indexed`, `Queued for indexing`, `Indexing…`, `Indexing failed`, `Not indexable`. - Vector indexing currently supports `.txt`, `.md`, `.docx`, `.pdf`, and `.pptx`. - Exact storage search is broader and can extract text from formats such as `docx`, `xlsx`, `pptx`, and `pdf`. - Valid uploads can still show `Not indexable`.

- `GET /api/organizations/{orgId}/storage?path=...` - `GET /api/organizations/{orgId}/storage/stats?path=...` - `POST /api/organizations/{orgId}/storage/upload` - `GET /api/organizations/{orgId}/storage/download?path=...` - `DELETE /api/organizations/{orgId}/storage/file?path=...` - `POST /api/organizations/{orgId}/storage/folder` - `POST /api/organizations/{orgId}/storage/folder/rename` - `POST /api/organizations/{orgId}/storage/folder/copy` - `POST /api/organizations/{orgId}/storage/folder/move` - `GET /api/organizations/{orgId}/storage/file/content?path=...` - `PUT /api/organizations/{orgId}/storage/file/content` - `GET /api/organizations/{orgId}/storage/folder/share?path=...` - `POST /api/organizations/{orgId}/storage/folder/share` - `DELETE /api/organizations/{orgId}/storage/folder/share`

- `GET/PUT /storage/file/content` only allow existing `.txt` and `.md` files. - Upload is capped at `10 MB` by the API upload route. The cowork content route is existing-file only; current code does not show a separate content-endpoint size rule beyond file handling in the caller.

- Non-system AI teammates are still limited to folders explicitly shared with them. - `storage.list` returns only content inside shared folders for non-system AI teammates. - `storage.semantic_search` searches indexed documents inside readable shared folders for non-system AI teammates. - `storage.search`, `storage.read_file`, `storage.read_image`, and `storage.stat_file` require readable shared-folder access for non-system AI teammates. - `storage.write_file` and `storage.edit_file` require writable shared-folder access for non-system AI teammates. - `storage.write_file` and `storage.edit_file` only support `.txt`, `.md`, `.htm`, `.html`, `.csv`, `.json`, `.yaml`, and `.yml`. - `storage.rename` requires the target path to be inside a writable shared folder for non-system AI teammates. - `storage.copy` requires readable source access and writable destination access for non-system AI teammates. - `storage.move` requires writable access to both source and destination for non-system AI teammates. - Ally uses system-level storage access.

- The backend emits `storage_file.created`, `storage_file.updated`, `storage_file.deleted`, `storage_file.renamed`, `storage_file.copied`, and `storage_file.moved`. - The current Storage file-list hook auto-refreshes on all six events. - Cowork document state also listens to rename and move events so an open document can follow its new path.

- The canonical private API reference now lives in `private-api.md`. - Private storage routes are under `{api_url}/api/private/storage`. - Current auth is `api-key: <TOKEN>` only.