Files

Upload, organize, and recover organization files.

Files belong to the organization and remain there when its members change. Ask the agent to upload documents and spreadsheets and organize access with folders.

Storage quota

The organization’s storage is in Activation and limits. Processed data for spreadsheet queries has a separate quota.

• limitBytes: the organization’s storage capacity.
• usedBytes: active and trashed files. Bytes are released after permanent deletion.
• reservedBytes: space reserved by uploads in progress.
• Available space: limitBytes - usedBytes - reservedBytes.

Trashing a file keeps its bytes accounted for. Restoring it during the recovery period consumes no additional space.

Upload through the agent

The agent uploads each file over MCP in this sequence:

1. Reserve the upload with upload_begin. Supply requestId, name, mediaType and size, plus a destination when needed. The server checks quota, reserves the declared size and returns the upload and transfer: a one-time link (url), the Upload-Token header and command, a ready curl.
2. Send the file. The agent runs transfer.command in its shell with FILE replaced by the local path. The PUT carries only the Upload-Token, never the connection’s token. The response is the completed upload (kind: "completed"); the file id is file.id. The server checks the size, activates the file and moves reserved space to used space. Repeating the PUT after completion returns the same file.
3. Over 64 MiB, send parts. Send each 8 MiB part (8,388,608 bytes) with PUT {url}?part=N, N from 1; the last part holds the rest. The upload completes when the last part arrives.

The link lasts one hour (until transfer.expiresAt) and acts as the connection that created it: if that connection is revoked or the person leaves the organization, the link stops working. Calling upload_begin again with the same requestId returns a fresh link for the same upload. An upload allows up to 10,000 parts: at most 83,886,080,000 bytes per file (78.125 GiB), within the organization’s available space.

In Codex, curl needs network access; see Connect Codex.

Reuse the same requestId (up to 200 characters) when retrying. A different name, destination or size with the same key fails with conflict; different bytes are also checked for file_write and sheet_write. upload_cancel cancels an unfinished upload and releases its reservation. Abandoned uploads expire and are cleaned up automatically.

Each tool lists its full parameters in its input schema; see MCP.

Trash and recovery

trash moves an active file to Trash for 30 days. It leaves the default listing and appears in list with state: "trash".

restore recovers the file before recover_until. Over MCP, it requires files:write and write access to the item. After the deadline, recovery becomes unavailable and automatic cleanup deletes the data.

No agent deletes an item immediately: any member with write access can trash and restore it, and Siglata deletes the item 30 days later, releasing its bytes after the stored data is removed. activity_list records who trashed the item, through which agent and when, as well as the deletion.

Rename and download

rename changes the name without copying content or consuming more space.

file_read returns content inline up to 128 KiB and two download paths:

• link: a Console address for a signed-in person to open in the browser.
• transfer: a one-time link for the agent itself to save the file, with the Download-Token header and command, a ready curl that writes the file under its name into the working directory. The link lasts 10 minutes and serves one download.

The download acts as the connection that called file_read: before sending bytes it checks the connection, organization membership and file access, and it is recorded in Activity.

Folders and Access Control

Files can live in nested folders, and every file and folder carries a visibility flag:

• org (default): Organization members can access it, subject to parent-folder restrictions and OAuth scopes. Writing in the company space also requires the permissions described there.
• restricted: Only the object’s creator, organization owner/admin members, and members holding an explicit grant, directly or through a team they belong to, can access the object.

A restricted folder restricts its entire subtree: to read or write an object, the caller must satisfy every restricted folder in its ancestor chain. A grant on a folder extends to its unrestricted descendants, while a restricted object inside a shared folder still requires its own grant.

• Denied operations fail with the forbidden error code; restricted objects a member cannot read are also omitted from list results.
• grant_set is limited to the object’s creator and organization administrators; it sets a grantee’s level, and level: null revokes it. Sharing operations exist only for Enterprise organizations.
• A grant goes to a member (granteeType: "user") or to a team (granteeType: "team") of the organization; any other id fails with invalid_input. A team grant applies to whoever is on the team at each request: someone who leaves the team loses access on the next request. With both a direct grant and a team grant, the higher level applies.
• set_visibility, like grant_set, is limited to the object’s creator and organization administrators; a write grant is not enough. It does not change existing grants.
• move and upload_begin into a folder require write access on the destination folder.
• Trashing a folder does not trash its contents; when a trashed folder passes its recovery deadline, it is deleted and its children move to the organization root.