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. 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), fileCount}.

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. Legacy { role:"name" } accepted. - 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, 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>"`.

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.