File tools

file · 14 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.

​

cohesive_file_copy

Hints — destructive Copy a file record to a new parent or path. 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.

​

cohesive_file_delete

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

​

cohesive_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 cohesive_file_read cannot return inline. Returns — JSON, as text content and as structured content.

​

cohesive_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, your recently modified Library files, and deleted, recently deleted files still restorable with cohesive_file_recover. Exactly one of: workspace, canvas, chat, 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.

​

cohesive_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 cohesive_file_move path. Not to be confused with the left-rail folders that organize canvases and chats themselves — those are a separate concept, and these directories only ever group file records. Exactly one of: workspace, canvas, chat. Returns — JSON, as text content and as structured content.

​

cohesive_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.

​

cohesive_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.

​

cohesive_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. “Public URL” (view_url in JSON) is the viewer page: the one to give a person. “Raw URL” (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 you show someone. Revoke with cohesive_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.

​

cohesive_file_read

Hints — read-only, idempotent Print 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 cohesive_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.

​

cohesive_file_recover

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

​

cohesive_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 (cohesive_file_copy) only when you want a separate file with a separate history. Referencing the same file in the same container twice is a no-op; the output says whether the reference already existed. Exactly one of: canvas, chat. Returns — JSON, as text content and as structured content.

​

cohesive_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 you can view. Returns — JSON, as text content and as structured content.

​

cohesive_file_unpublish

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

​

cohesive_file_upload

Hints — destructive Upload a file to a workspace, canvas, or chat. Uploads a file record under exactly one parent: a workspace, a canvas, or a chat (flow session). Pass the file’s text as content, or a public URL as from_url for the server to fetch and store the bytes. path is the destination and names the file exactly, extension included; a directory path has no file name to complete it here. It is required with content, and with from_url it can be omitted to let the server name the file from the URL. Processing (previews, text extraction, summary) continues server-side after upload; wait blocks until the record reaches status “processed”. Exactly one of: workspace, canvas, chat. 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.