File tools (files.write)

Create folders and files, rename, copy and add to files. Nothing here deletes, moves away or replaces what a file holds. An app has these only if an administrator agreed the files.write change for it and you agreed it when connecting.

append_spreadsheet_rows

Changes thingsScope: files.write

Add rows to the end of an existing CSV or XLSX spreadsheet. Give each row as a list of cell values; quoting is handled for you. At most 10000 rows and 4 MB per call; XLSX files up to 10 MB. Pivot tables in an XLSX are not kept.

Argument	Type	Required	What it is
share	string	Yes	The share’s name or id, from list_shares
path	string	Yes	Path of the existing CSV or XLSX inside the share
rows	list of array	Yes	The rows to add; each row a list of cell values (text, number, true/false or null)
sheet	string	No	XLSX only: the worksheet to add to, by its exact name (default: the first). A name the workbook does not have is refused

append_text_file

Changes thingsScope: files.write

Add text to the end of an existing TXT or MD file (a log, running notes). A line break is put before it if the file does not end with one. For CSV or XLSX rows use append_spreadsheet_rows. At most 4 MB of text per call.

Argument	Type	Required	What it is
share	string	Yes	The share’s name or id, from list_shares
path	string	Yes	Path of the existing file inside the share
content	string	Yes	The text to add

copy_files

Changes thingsScope: files.write

Copy files (not folders) into a folder, leaving the originals where they are. At most 50 files per call. A name already taken in the destination gets a new name; the result gives each copy’s path. A file too large to copy here (over 64 MB into another share, over 1 GB within one) is not copied: it is listed as failed.

The destination folder must already exist. To copy into another share, pass its name or id as target_share; that share must also be one this app may change.

Argument	Type	Required	What it is
share	string	Yes	The share the files are in, by name or id from list_shares
paths	list of string	Yes	Paths of the files to copy, inside the share
destination	string	No	The folder to copy them into; ”/” or empty for the top of the destination share
target_share	string	No	The share to copy into, if not the same one (default: the same share)

create_file

Changes thingsScope: files.write

Create a new file in a folder of a share. It never replaces a file: a name already taken in that folder is refused, so pick another.

Pick format and give the matching body:

• docx, pdf -> sections (blocks)
• txt, md, json, html -> content (the text)
• xlsx, csv -> sheets (array of {name?, headers?, rows})

Section blocks: {“type”:“heading”,“level”:1|2|3,“text”:”…”}, {“type”:“paragraph”,“text”:”…”}, {“type”:“list”,“items”:[”…”],“ordered”:bool?}, {“type”:“table”,“headers”:[”…”],“rows”:[[”…”]]}, {“type”:“page_break”}. Sheets: {“name”:“Sheet1”,“headers”:[“A”,“B”],“rows”:[[“a”,1]]}; csv takes one sheet; at most 10000 rows a sheet.

At most 4 MB of content per call: for more, create the file with the first part and add the rest with append_text_file or append_spreadsheet_rows.

Argument	Type	Required	What it is
share	string	Yes	The share’s name or id, from list_shares
filename	string	Yes	The new file’s name; the extension is added from format if missing
format	string	Yes	One of: “docx”, “pdf”, “txt”, “md”, “json”, “html”, “xlsx”, “csv”
folder	string	No	The folder to create it in; ”/” or empty for the top of the share (default ”/”)
sections	list of object	No	For docx and pdf only
content	string	No	For txt, md, json and html only
sheets	list of object	No	For xlsx and csv only

create_folder

Changes thingsScope: files.write

Create a new folder in a share. A name already taken in that folder is refused.

Argument	Type	Required	What it is
share	string	Yes	The share’s name or id, from list_shares
name	string	Yes	The new folder’s name (no ”/”)
path	string	No	The folder to create it in; ”/” or empty for the top of the share (default ”/”)

rename_file

Changes thingsScope: files.write

Rename one file in a share (not a folder). The new name is a name only, with no ”/”, and must not already be taken in that folder (nothing is replaced).

Argument	Type	Required	What it is
share	string	Yes	The share’s name or id, from list_shares
path	string	Yes	Path of the file inside the share
new_name	string	Yes	The new name, including its extension

restore_version_as_copy

Changes thingsScope: files.write

Write an earlier version of a file as a NEW file beside it, named like “Report (3 Nov 2026 14.02).docx” (the first free name). Nothing is replaced: the file keeps its current contents, so this is safe on every storage. Take the version_id from list_versions. Replacing the file itself with an old version is not offered here; do that in Foldr.

Argument	Type	Required	What it is
share	string	Yes	The share’s name or id, from list_shares
path	string	Yes	Path of the file inside the share
version_id	string	Yes	The version’s id, from list_versions