File tools

file · 18 tools · Mounted by default Files & Docs live under a Workspace, a Canvas, or a chat. These tools list them, read them, move them, and hand out links to them. Every call also carries an exit code and timing in _meta, and errors come back as results rather than transport failures. See Results.

file_copy

Hints — destructive Copy a file record to a new parent or path, and place the copy. Copies a file record to a new destination; the source is untouched. The path rule matches upload. overwrite replaces the contents of an existing record at the destination path, preserving its ID and share state. Exactly one of: workspace, canvas, chat. Returns — JSON, as text content and as structured content.

file_delete

Hints — destructive Delete a file record. Soft-deletes a file record. Recently deleted records can be restored with file_recover. Returns — JSON, as text content and as structured content.

file_display

Hints — destructive Change how an .html file renders: block or document, kind, chromeless, natural box. Rewrites the display of an .html file — the identity every node showing it follows: block or document, the block’s kind (app or static), chromeless, and the natural box a later placement lands at. Only the flags passed change. A kind that becomes static is checked against the stored HTML: scripts, handlers and forms are refused. Nodes already on a canvas keep their position, box and layer; those are the node’s (canvas_node_move, canvas_node_resize, and the layer through canvas_node_update). At most one of: block, document. At most one of: chromeless, no_chromeless. Returns — JSON, as text content and as structured content.

file_get

Hints — read-only, idempotent Show one file record. view_url is the URL to show a person; raw_url serves the bytes for fetching or embedding and is not for people; dashboard_url opens the record in the app for a signed-in user. download_url is a signed link to the bytes, valid until download_url_expires_at: the way to move a file anywhere, or to read one file_read cannot return inline. Returns — JSON, as text content and as structured content.

file_list

Hints — read-only, idempotent List file records under one parent resource, recent files, or deleted files. Lists file records scoped to exactly one parent — a workspace, a canvas, or a chat (flow session) — or one of two cross-workspace views (newest first; page with before): recent, the signed-in account’s recently modified Library files, and deleted, recently deleted files still restorable with file_recover. A workspace’s canvases sit in the same tree as its files. They are left out by default; kinds picks the row kinds to list (file, folder, link, canvas), so kinds canvas is the canvas tree and kinds file,folder,link,canvas the whole workspace tree. Exactly one of: workspace, canvas, chat, recent, deleted. At most one of: kinds, recent, deleted. view_url is the URL to show a person; raw_url serves the bytes for fetching or embedding and is not for people; dashboard_url opens the record in the app for a signed-in user. Returns — JSON, as text content and as structured content.

file_mkdir

Hints — idempotent Create an empty file-system directory. Creates a folder-kind file record — a file-system directory — under exactly one parent: a workspace, a canvas, or a chat (flow session). Directories normally come into being when a file path names them; mkdir exists so an empty directory can be prepared before files move in. Organizing files into folders is this plus file_move path. A workspace’s directories are its tree: the folders the left rail shows, holding Library files and canvases alike. canvas_move folder files a canvas into one, and an empty directory stays around only when created here. Exactly one of: workspace, canvas, chat. Returns — JSON, as text content and as structured content.

file_move

Hints — destructive, idempotent Move a file record to a new parent or path. Moves a file record to a new destination. The path rule matches upload: no extension or a trailing / means a directory (the current file name is kept); an extensioned path renames. Omitting path keeps the name at the destination root. Exactly one of: workspace, canvas, chat. Returns — JSON, as text content and as structured content.

file_promote

Hints — destructive Move a canvas or chat file into the workspace Library. Moves a canvas or chat file into the workspace Library — what dragging it to the Library does in the app. The file keeps its ID, and a reference (a link record) is left behind in its source container in the same action, so the canvas or chat still shows the file, now pointing at its Library home. workspace defaults to the source container’s workspace, and parent_path places the file under a Library directory (default: the Library root). Returns — JSON, as text content and as structured content.

file_publish

Hints — idempotent Publish a file record to a public URL. Makes a file record publicly readable — anyone with the URL can view it, no Cohesive account needed. Two URLs come back. view_url is the viewer page: the one to give a person. raw_url serves the file’s bytes: use it to fetch the content, embed the file in another file, or hand it to another service — never as the URL to show someone. Revoke with file_unpublish. view_url is the URL to show a person; raw_url serves the bytes for fetching or embedding and is not for people; dashboard_url opens the record in the app for a signed-in user. Returns — JSON, as text content and as structured content.

file_read

Hints — read-only, idempotent Read a file record’s content. Returns a file record’s bytes. For reading, not transfer: text comes back inline up to the output cap and an image up to 3 MiB as an image block; anything else is refused. To move a file anywhere, or read one that does not fit, use file_get and hand its download_url to whatever needs the bytes. Returns — The file’s own bytes — text inline, images as an image block, and a pointer to cohesive_file_get when neither fits.

file_recover

Hints — idempotent Restore a recently deleted file record. Returns — JSON, as text content and as structured content.

file_reference

Hints — writes (no read-only or destructive hint) Place a reference to a file on a canvas or in a chat. Creates a reference to a file: the reference is its own file record (kind “link”) living in the canvas or chat and pointing at the workspace file. The file itself does not move — this is how a Library file, including one from another workspace, is placed onto a canvas without copying it. Copy instead (file_copy) only when a separate file with a separate history is wanted. Referencing the same file in the same container twice is a no-op; the result says whether the reference already existed. Exactly one of: canvas, chat. Returns — JSON, as text content and as structured content.

file_references

Hints — read-only, idempotent List the references pointing at a file. Lists the link records that reference this file from canvases and chats. The listing is filtered to the containers the signed-in account can view. Returns — JSON, as text content and as structured content.

file_state_get

Hints — read-only, idempotent Read an HTML block’s state. Reads one key-ordered page of an HTML block’s state: every key, or with prefix the key equal to it and every key under it (“votes” reads votes and votes/…). When pagination.next is set, more keys remain: pass it as after. Each row carries its value, version and authors’ user IDs. The canvas-html-blocks skill’s references/state.md covers key layout. Returns — JSON, as text content and as structured content.

file_state_update

Hints — destructive Write an HTML block’s state. Applies a batch of operations to an HTML block’s state, as the person the session belongs to, and returns the rows they named as they now stand. payload is {"ops": [...]}; each op is one of {"op":"set","key","value","if_version"}, {"op":"delete","key","if_version"}, {"op":"increment","key","by"}, {"op":"delete_prefix","prefix"}. if_version fails the whole batch unless the key is at that version (0: must not exist). The canvas-html-blocks skill’s references/state.md covers key layout. Returns — JSON, as text content and as structured content.

file_unpublish

Hints — destructive Revoke a file record’s public URL. Returns — JSON, as text content and as structured content.

file_upload

Hints — destructive Create a file, replace its bytes, or place it on a canvas. Creates a file record under one parent, a workspace, a canvas or a chat, from its text as content or from a public URL as from_url; with canvas, position also places it, as a card, an HTML page card (document) or a live HTML block (block app|static with width and height). overwrite replaces the bytes of the record at path and id replaces the bytes of a record by its id; both keep its id, its node, its display and its state. A replace returns once the new bytes are live (a read right after sees them), no_wait returns as soon as they are sent, wait after processing too. At most one of: block, document. Exactly one of: workspace, canvas, chat, id. At most one of: id, document. At most one of: id, path. At most one of: id, position. At most one of: wait, no_wait. Exactly one of: content, from_url. There is no base64 property: never encode file bytes into a call. Returns — JSON, as text content and as structured content.

file_view

Hints — read-only, idempotent Show a file inline. Hosts that support MCP Apps show the file in the conversation: an image at full size, markdown, text and CSV rendered, anything else as its preview with a link into Cohesive. The result is also the record file_get returns. To read the contents, use file_read; to move the bytes, use the download_url from file_get. view_url is the URL to show a person; raw_url serves the bytes for fetching or embedding and is not for people; dashboard_url opens the record in the app for a signed-in user. Returns — JSON, as text content and as structured content.