Files and attachments

A document is a folder. index.html is the entry point; anything else in the folder is reachable by relative path from the document's URL. This is how an HTML page gets its assets, and how a markdown document can reference an image.

Adding a file

From an agent:

put_file(doc_id, path="img/chart.png", content_base64="...")
put_file(doc_id, path="style.css", content="body { ... }")

Pass exactly one of content (text) or content_base64 (binary). The response includes the updated document and files, the full list of paths in the new version, plus changed. Replacing a path with identical bytes is a no-op.

From the app or a script with a session cookie, POST /api/docs/{id}/files accepts multipart form data: one file with an optional path field, or several parts named files whose file names become paths.

Paths

A path is a safe relative path such as style.css or img/chart.png:

• no leading slash, no .., no empty segments;
• at most five levels deep;
• a plain file name with an extension the server knows how to serve.

Invalid paths are rejected with a 400 and the reason.

Listing and reading

list_files(doc_id) returns every path in the current version with size, SHA-256 and content type. GET /api/docs/{id} returns the same list.

To read a text file back, get_file(doc_id, path) returns its content, whole or by line range, for any text file up to 1 MiB; grep_doc searches inside it and edit_file and apply_patch change it. See Search and edit. Binary files are fetched from the document URL like any visitor would.

Removing a file

delete_file(doc_id, path) or DELETE /api/docs/{id}/files?path=.... Two files cannot be removed: index.html, and the primary content of a snippet, markdown document or file share (source.<ext>, source.md, or the shared file). Update or delete the document instead.

Sizes

Each file added through a tool call is capped at 20 MiB decoded. The whole document is capped at 20 MiB, except a file share, whose single streamed upload may be up to 2 GiB. Adding files counts against your workspace storage.

Large files

For anything over 20 MiB, do not base64 it through a tool call. Use create_upload to mint a one-time upload URL and stream the file with curl -T. The result is a new file-share document, not a file inside an existing one. See Kinds and formats and the MCP reference.

How files are served

Every file is served with X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer and X-Robots-Tag: noindex, nofollow. HTML and SVG carry the sandbox Content-Security-Policy. Types that browsers should not render inline, such as zip, are sent as attachments. Unlisted documents get an ETag so unchanged files return 304; gated documents are no-store. Range requests are honored for seeking and resumed downloads.