files_tool
Site file manager on the selected site (call select_site first). Proxies to /uapi/files with a server-minted Bearer key. Path is a parameter, never a URL suffix. Empty path is the site root, except content_get, content_put, and mkdir, where the API rejects it. Path bytes are only A-Z a-z 0-9 . _ / -; segments cannot be empty, ".", "..", or start with a dot. Batch upload, upload_url, rename with items, move with paths, and delete return the API body with results even when an item has state=error. A tool error is only a failed whole request (error.code). Read limits with action=quota; do not hardcode them. Shell fast path for binaries: never read binary files into model context. Mint upload_direct, POST raw bytes with curl to its upload_url, then pass the returned upload_id to action=upload with path (file manager) or to the module update as *_upload_id. Inline content_base64 is for small files only; large base64 produced by a model arrives truncated. Pass size and sha256 of the local file with inline bodies: a mismatch fails the call before anything is stored, and a successful upload returns sent with both. content_get reads text files only; anything else comes back as FM_NOT_TEXT or FM_TOO_LARGE_TO_READ.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | upload_url: http:// or https:// URL that ends with a file name and extension. | |
| file | No | upload: synonym for a single text body when files and content are omitted. | |
| name | No | upload: saved name when the request has exactly one file. upload_url: saved name, or the last URL segment when omitted. rename: new leaf name (no slashes) for a single object. | |
| path | No | Clean path without edge slashes. Empty string is the site root. Folder for list, info, upload, upload_url, and move destination context; file for content_*; new folder for mkdir; source for rename, move, and delete. | |
| size | No | upload_direct: exact byte size of the file that will be POSTed to upload_url (1..16777216). The curl body must match it exactly. upload: expected byte size of the single top-level body after base64 decoding; a mismatch fails the call. | |
| sort | No | list: name (default), size, or mtime. Anything else is treated as name by the API. | |
| files | No | upload: one or more files. Each item is { filename, content } or { filename, content_base64 }. Sent as a repeated multipart field named file. name applies only when this list has one file and no extra top-level body. | |
| items | No | rename batch: map of leaf name to new leaf name inside path. When this object is present the API always returns HTTP 200 and results, even if name is also set. | |
| limit | No | list: slice length. 0 (default) means the rest of the listing. | |
| order | No | list: asc (default). Only desc changes direction. | |
| paths | No | move: sources to move; a non-empty list ignores path and always returns HTTP 200. delete: targets, together with path. Items are clean paths. | |
| action | Yes | list — GET /uapi/files (default path is root, sort=name, no filter). info — GET /uapi/files/info. content_get — GET /uapi/files/content. content_put — PUT /uapi/files/content. quota — GET /uapi/files/quota, no arguments. upload — POST /uapi/files/upload (multipart field file, repeatable); bytes come from files/content/content_base64 and from upload_id/upload_ids. upload_url — POST /uapi/files/upload_url. upload_direct — mint a one-shot curl URL (filename and size; call select_site first). POST the raw file to upload_url. The response is upload_id, filename, size, and sha256. Pass that upload_id to action=upload with path to place it in the file manager, or to content_tool or shop_tool as *_upload_id when updating the material. mkdir — POST /uapi/files/mkdir. rename — POST /uapi/files/rename (one object fails the request; items is always HTTP 200). move — POST /uapi/files/move (one path fails the request; paths is always HTTP 200). delete — DELETE /uapi/files (confirm; missing targets fail the request, otherwise HTTP 200 with results). | |
| create | No | content_put: create the file when it does not exist. Default false. Parent folder must already exist. | |
| filter | No | list: a quota.limits.filters name, or a comma-separated extension list (png,jpg). Unknown names are ignored by the API. | |
| offset | No | list: slice start after sorting. Default 0. | |
| sha256 | No | upload: expected SHA-256 hex of the single top-level body after base64 decoding; a mismatch fails the call. | |
| confirm | No | Required for delete after explicit user approval. | |
| content | No | content_put: new file text (empty string is allowed). upload: text body of a single file when files is omitted. | |
| filename | No | upload and upload_direct: original file name (multipart filename). Falls back to name. | |
| add_wmark | No | upload and upload_url: apply the site watermark when it is enabled and the extension is an allowed image. | |
| upload_id | No | upload: id from upload_direct whose bytes were already POSTed. Saved into path under its upload_direct filename, or name when it is the only file. Spent only when that item is uploaded; otherwise it stays usable until it expires. | |
| upload_ids | No | upload: several upload_direct ids (a comma-separated string is accepted too), sent after upload_id and inline files. At most 20. | |
| destination | No | move: existing destination folder. Empty string is the site root. | |
| content_base64 | No | upload: standard base64 body of a single binary file when files is omitted. Foreign characters or a truncated length fail the call. |