Files Tools

List user files. Optional params: folderId (filter by folder, use "root" for root level), conversationId, sortBy ("uploadedAt", "size", "fileName"), sortOrder ("asc", "desc"), limit, offset. Returns {files[], total}.

Get file details with content. Param "fileId" from list. Returns file metadata and binary content. Only works for files that have stored content — a file with none returns a not-found error.

Get a temporary download URL. Param "fileId". Returns { url, expiresAt, fileName, mimeType, size } — a signed link on the Serenities domain that needs no auth header, made for you and valid for 10 minutes (it stops working at once if you leave the workspace; ask again for a new one, never store or share it). Only works for files that have stored content.

Move file to trash. A file in the trash still counts toward storage until it is deleted for good: files_emptyTrash empties the trash and files_deleteForGood deletes chosen trashed files (both after files_previewTrash). Param "fileId". Act only on what the person named or picked.

Rename a file. Params: fileId, newName (new filename with extension).

Move file to folder. Params: fileId, folderId (target folder ID, or null for root). A file with no rules of its own takes the new folder's, so moving it into a shared folder shares it: in the built-in chat that asks the person first (a card), unless the chat is in "Don't ask".

Copy a file. Params: fileId, withoutPassword (must be true when the file has a password: the copy leaves the password behind; the original keeps it), folderId (optional; left out = the original's folder, null = root), name (optional; left out = the original's name). The copy always starts private: it opens to no one but your workspace, whatever the original's rules. Takes storage like an upload. Returns { id, originalName, mimeType, size, folderId }. Use it when a password-protected file should be a site's logo or favicon: copy it without the password, then set the copy.

List folders. Optional param "parentId" (null for root level folders). Returns array with id, name, parentId.

Create a folder. Params: name (required), parentId (optional, null for root level).

Rename folder. Params: folderId, newName.

Delete empty folder. Param "folderId". Fails if folder has contents. Act only on what the person named or picked.

Get storage stats. No params. Returns {totalSize (bytes; every stored file, the trash included), fileCount (files not in the trash)}.

What is in the trash, before deleting for good. No params. Returns { count, bytes } of every file in the trash (they still count toward storage), nextBatch { count, bytes } (the files the next files_emptyTrash deletes: at most 1,000, oldest first) and files (at most 20: id, name, size). Show the person these numbers, then call files_emptyTrash with nextBatch.count and nextBatch.bytes, or files_deleteForGood for chosen files. Files only: folders in the trash are not counted.

Delete chosen files in the trash for good, freeing their storage. This cannot be undone: the files cannot be restored. Params: fileIds (ids of files in the trash, from files_previewTrash or files you moved there with files_delete; at most 1,000), expectedCount and expectedBytes (how many of these files are in the trash and their size in bytes, as you showed the person). Only this workspace's files that are in the trash are deleted; a live file is never deleted (move it to the trash with files_delete first). If expectedCount or expectedBytes no longer match what would be deleted, nothing is deleted and the error gives the current numbers. Returns { deletedCount, deletedBytes, message }. Act only on what the person named or picked.

Empty the trash for good, freeing storage. This cannot be undone: the files cannot be restored. Call files_previewTrash first, show the person the numbers, then call this with expectedCount = nextBatch.count and expectedBytes = nextBatch.bytes. One call deletes the next batch (at most 1,000 files); if more remain, the answer says so: preview and call again. If the numbers no longer match, nothing is deleted and the error gives the current numbers. Only files are deleted for good; folders in the trash stay in the trash. Returns { deletedCount, deletedBytes, message }. Act only on what the person named or picked.

Set access rules for a file in published apps. Controls who can create/read/delete files. Params: - fileId: File ID (required) - accessRules: Object with rules per operation (create, read, delete). Omitting `read` makes the file private (owner only): it no longer inherits its folder's sharing. - trackCreator: boolean (default true) - Track who uploads each file - accessRules.sites: [siteId] - the file's HOME sites besides the site it was uploaded through. Only home-site members count for authenticated / has_role / has_entitlement / user_property, and through any other site (or its bare link) the file opens only if its rule says "Anyone, everywhere". Left out = keep the saved list. Each operation's value is a CONDITION: a single rule, a flat array (OR), or a boolean group ({ all | any | not }) — same shape as tables.setAccessRules. Rule types (leaves): - public, two levels: { type: "public", scope: "home" } = "Anyone on this site" (only through the file's home sites); { type: "public", scope: "everywhere" } = "Anyone, everywhere" (any of your sites and the file's public link). A public rule with no level keeps the saved one; a file made public now that has a home site starts as "Anyone on this site". Once the newer levels "Only through this site" / "Anyone on the internet" are switched on (see tables_setAccessRules), a public rule with no level that is new or changed is refused naming both instead: always say the level. A file with NO site (a Drive file) made public must say which: name its sites in accessRules.sites, or scope "everywhere" — refused otherwise. - authenticated, creator - user_property: { type: "user_property", field, value?, op? } - op: eq/ne/gt/gte/lt/lte/in/nin/contains/isEmpty/isNotEmpty - has_role: { type: "has_role", roleId: "<uuid>" } - from listProjectRoles. A site role given by its name ({ role: "name" }) is refused; only the built-in "user" / "admin" may be named. Pages: see setPageAccessRules. - email: { type: "email", email: "..." } - has_entitlement: { type: "has_entitlement", key } - members holding that paid entitlement - function: { type: "function", functionId: "<id>" } - decided by a backend function returning true/false (field_match and relationship can't be used on files: saving one is refused, and a stored one denies everyone.) Groups: { any:[...] } = OR (flat array shorthand), { all:[...] } = AND, { not: cond } = NOT. Nest freely. IMPORTANT: App owner always has full access. No rules = deny (secure by default). Example - Public download for everyone, only creator can delete: { "fileId": "xxx", "accessRules": { "read": [{"type": "public", "scope": "everywhere"}], "delete": [{"type": "creator"}] } }

Get current access rules for a file. Returns rules and trackCreator setting. Params: fileId (required) Returns: - fileId - accessRules: Current rules per operation - trackCreator: Whether file uploaders are tracked

Get the access rules applied to a folder's files. Param: folderId (required).

Set access rules for ALL files in a folder at once (bulk version of setAccessRules — same Condition shape). A public rule made now must say its level: { type: "public", scope: "everywhere" } (anyone, through any site and the link) or scope "home" (each file through its own site) — a bare public is refused. Params: folderId (required), accessRules (per-operation create/read/delete rules). Use after uploading a batch of files that the published app must read. Omitting `read` makes the folder private (owner only) — it no longer inherits a parent's sharing. Subfolders with rules of their own keep them.

Get storage quota info. Returns usedBytes (the trash included: files count until deleted for good), limitBytes, availableBytes, maxFileSizeBytes, percentUsed. Call BEFORE upload to check available space.

PREFERRED way to upload a file. Returns a one-shot URL to PUT the raw bytes at, so a file NEVER has to be written into the conversation as base64. Params: fileName, sizeBytes (exact byte length), mimeType (optional), folderId (optional). Returns { uploadUrl, method: "PUT", headers, expiresAt, fileId comes back from the upload }. The plan limit and remaining storage are checked BEFORE the link is issued, so a file that will not fit is refused up front with availableBytes — you never upload and then discover there was no room. The link needs no auth header, is single use, expires in 10 minutes, and is capped at 100MB (use the web interface above that). Typical use: call this, then `curl -X PUT --data-binary @file "<uploadUrl>"`. Refused for a folder that lets in "Anyone on the internet" (a link can't wait for the person's OK): use files_upload there, which asks them.

Upload a file (max 500MB). Params: fileName (required), then EXACTLY ONE of sourceUrl or content, plus mimeType (optional) and folderId (optional). PREFER sourceUrl — an HTTPS URL the server fetches itself (a private or local address is refused and a redirect is not followed: pass the final URL), so the bytes never pass through this conversation; base64 `content` costs roughly 4 tokens for every 3 bytes, which makes a handful of PDFs cost more than the rest of the task. Use content only when the file exists nowhere fetchable. Same extension, size, quota and folder rules either way, and quota is validated BEFORE accepting. Call getQuota first to check available space. Into a folder that lets in "Anyone on the internet" it answers pendingChange: a card a person taps, and nothing is stored until then (say so); that card holds at most about 2 MB of content, so give a bigger file as sourceUrl.