Get startedCLIAPIMCPWebDesktopAgentsSupportBillingChangelog
Guide

Files surface

A folder tree where any media, document, or archive lives next to the data and prose it relates to. Same first-class surface as tables, docs, and HTML; same sharing, same audit log. Drop a screenshot into the workspace it belongs to, no separate file app required.

Creating a Files surface

Click the “+” at the right end of the surface tab bar, then pick the Files tile. The surface lands as an empty folder tree ready to drop files into.

Files surfaces coexist with tables, docs, and HTML in the same workspace. A workspace can have any number of any kind, in any order. Drag the tab to reorder.

Uploading files

Three ways:

  • Drag and drop from your desktop into the surface body. The dropzone highlights when files are being dragged over it; release to upload.
  • Click “+ Upload” in the toolbar. Opens your OS file picker (multi-file selection supported).
  • Drag files into a sub-folder. Navigate into a folder first; the upload lands in that folder, not at the root.

Upload progress shows in a floating widget at the bottom-right with one row per file. Cancel or retry per row. The widget auto-dismisses two seconds after the last upload completes.

Storage caps

Tier
Total storage
Per-file cap
Free
5 GB
5 MB
Pro
100 GB
100 MB
Scale
500 GB
1 GB

Storage usage is per org, summed across every Files surface in every workspace. Visible in Settings → Files with a breakdown by file type. Trash counts toward your cap until the 30-day cleanup window expires.

Supported file types

Default-deny allowlist for security. The current set:

  • Images: PNG, JPEG, WebP, GIF, AVIF, HEIC
  • Video: MP4, WebM, QuickTime
  • Audio: MP3, WAV, OGG, M4A, WebM
  • Documents: PDF, Word (.doc, .docx), Excel (.xls, .xlsx), PowerPoint (.ppt, .pptx)
  • Text: plain text, Markdown, CSV, JSON, XML
  • Archives: ZIP, TAR, GZip, 7z (never extracted server-side)

Need a type that isn’t on the list? Email support@trydock.ai with the use case and we’ll add it (or explain why we won’t).

In-browser preview

Click any file to open the preview modal. Images, video, audio, and PDFs render inline. Other file types show a download button. The modal carries the file’s display name, size, and quick actions (download, delete, close).

Folders + navigation

Click “+ Folder” to create a folder. Name it and it appears in the current view. Click a folder to navigate into it; the breadcrumb above the body updates. Click any segment of the breadcrumb to jump back up the tree.

Folders nest arbitrarily deep. Each folder belongs to one Files surface (folders don’t cross surfaces).

Delete + Trash

Open any file’s preview and click the delete icon, or cmd/ctrl-click multiple files in the grid to select them, then delete via the floating bulk-action bar at the bottom.

Deleted files move to Trash for 30 days before being permanently removed. Click Trash in the toolbar to view soft-deleted files; each row shows the days remaining. Click Restore to recover.

Security model

  • MIME sniffed from magic bytes server-side. Never trusts the client-declared Content-Type, so a file uploaded as image/jpegthat’s actually a Windows executable gets rejected.
  • Filenames sanitized:NFC-normalized, control characters stripped, length-capped at 255. The user’s filename is metadata only; the storage key is an opaque cuid (no path traversal possible).
  • Quota enforced at uploadwith a SELECT FOR UPDATE lock on the org row so concurrent uploads can’t collectively exceed the cap.
  • Soft-delete window means accidental deletes are reversible for 30 days.

API

The endpoints for programmatic access:

# List folder contents
GET /api/workspaces/{slug}/files?surfaceSlug={surface}&parentFolderId={id|null}

# Upload (use @vercel/blob/client `upload()` against this endpoint)
POST /api/workspaces/{slug}/files

# Download URL
GET /api/workspaces/{slug}/files/{fileId}/download

# Metadata
GET /api/workspaces/{slug}/files/{fileId}

# Soft-delete
DELETE /api/workspaces/{slug}/files/{fileId}

# Restore
PATCH /api/workspaces/{slug}/files/{fileId}  body: { restore: true }

# List trash
GET /api/workspaces/{slug}/files/trash?surfaceSlug={surface}

# Create folder
POST /api/workspaces/{slug}/folders  body: { surfaceSlug, parentFolderId?, name }

# Storage usage
GET /api/orgs/{slug}/storage

Frequently asked questions

Can agents upload files?
Not in v1. Upload stays user-only while we design the consent + per-agent size budgets. Agents can list, get metadata, and delete files via the MCP tools shipping in a follow-up.
What happens when I delete a folder?
Folder soft-delete cascades to files inside via the service layer. Restoring the folder restores the children. After 30 days, the cleanup cron hard-deletes the folder + every descendant file + refunds the storage to your cap.
Can I move a file to a different workspace?
Not yet. Single-workspace only in v1. Cross-workspace move is queued for v1.1.
Is there a public-link share for individual files?
Not in v1. The pattern works for whole workspaces (visibility = public/unlisted) but per-file public links land after the public-workspace pattern proves out at scale.
Why isn't SVG supported?
SVG can carry executable JavaScript and external references. v1 excludes SVG from the allowlist; v2 wires DOMPurify sanitization server-side and re-enables it.