---
title: "Writes content to a file, creating it if it doesn't exist. If the path is a symbolic link, the target file is written to (symlink is followed)."
method: POST
path: "/v1/{name}/filesystem:writeFile"
tags: ["FilesystemService"]
---

# Writes content to a file, creating it if it doesn't exist. If the path is a symbolic link, the target file is written to (symlink is followed).

`POST /v1/{name}/filesystem:writeFile`

## Request

- Base URL: `https://docs.h2o.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.h2o.ai/v1/{name}/filesystem:writeFile`
- Auth: none declared
- TypeScript: <https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto/docs/v1/:name/filesystem:writeFile/post.ts> (a function with typed inputs; its response is checked against the schema)

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

## Path parameters

- `name` string, required

## Request body

- object: Request to write a file.
  - `path` string, required: Required. The path where the file should be written. All paths are rooted at the sandbox filesystem root. Must start with a forward slash (e.g., "/app.js", "/workspace/data.csv"). If the file exists, it will be overwritten unless overwrite=false. If the file doesn't exist, it will be created with 0644 permissions (rw-r--r--), unless a custom mode is specified. Parent directories must exist unless create_parent_directories is true.
  - `content` string, byte, required: Required. The raw content to write to the file as bytes. For text files, provide UTF-8 encoded text. For binary files, provide raw binary data.
  - `createParentDirectories` boolean: Optional. If true, creates parent directories if they don't exist. If false or unspecified, the write will fail if parent directories don't exist.
  - `overwrite` boolean, nullable: Optional. Controls overwrite behavior for existing files. If true or unspecified, overwrites the file if it already exists. If explicitly set to false, the operation will fail if the file already exists. This allows atomic create-new-only semantics (similar to O_CREAT|O_EXCL).
  - `mode` string: Optional. Unix file mode and permission bits in octal notation. The format follows standard Unix permissions represented as a string. Examples: "0644" (rw-r--r--), "0755" (rwxr-xr-x), "0600" (rw-------). If not specified, defaults to "0644" for new files. When overwriting an existing file, the mode is only applied if this field is explicitly set.

## Response `200`

A successful response.

- V1WriteFileResponse: Response from writing a file.
  - `fileInfo` V1FileInfo: FileInfo contains metadata about a file or directory.
    - `path` string: Output only. The absolute path of the file or directory.
    - `size` string, int64: Output only. The size of the file in bytes. For directories, this is typically 0 or the size of the directory metadata.
    - `type` 'FILE_TYPE_UNSPECIFIED' | 'FILE_TYPE_REGULAR' | 'FILE_TYPE_DIRECTORY' | 'FILE_TYPE_SYMLINK': FileType indicates the type of filesystem entry. - FILE_TYPE_UNSPECIFIED: The file type is not specified. - FILE_TYPE_REGULAR: A regular file. - FILE_TYPE_DIRECTORY: A directory. - FILE_TYPE_SYMLINK: A symbolic link.
    - `modifyTime` string, date-time: Output only. The last modification time of the file or directory (mtime).
    - `mode` string: Output only. Unix file mode and permission bits in octal notation. The format follows standard Unix permissions represented as a string. Examples: "0644" (rw-r--r--), "0755" (rwxr-xr-x), "0777" (rwxrwxrwx).

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto.md) - [All operations](https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto/llms.txt) - [OpenAPI document](https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto/revisions/297cfadc1d39?raw)