What it does
Write content to a file in the Undisk workspace. Automatically creates an immutable version, so the previous content is preserved and can be restored anytime via restore_version. Creates the file if it doesn’t exist, or updates it if it does (upsert). Use create_file instead when you need a strict ‘file must not exist’ guard. Supports UTF-8 text by default, or raw binary bytes when content is base64-encoded with encoding=‘base64’. Returns the new version metadata including version ID and content hash.Required scope
files:write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | File path within the workspace (e.g., ‘src/config.json’) |
content | string | Yes | File content. Use plain UTF-8 text by default, or base64-encoded bytes when encoding=‘base64’. |
encoding | string | No | Content encoding. Defaults to ‘utf-8’. Use ‘base64’ for binary files. Values: utf-8, base64. |
if_version | number | No | Optional optimistic lock. If provided, the write only succeeds when the file’s current version number matches this value. Returns a 409 version_conflict error on mismatch. Use to prevent concurrent agents from overwriting each other. Pass 0 to require the file does not yet exist. |