# POST /files/write

Create a file or replace a known version.

This is a device HTTP route. Set `DEVICE_URL` to your reachable device URL; [connection and examples](https://mcp.applesauceos.com/doc/http.md) explain how. Do not append this path to the public MCP URL.

## Parameters

| Parameter | Type | Meaning |
| --- | --- | --- |
| `path` | JSON string | Required relative file path; parent directories are created. |
| `content` | JSON string | Required file content, UTF-8 text or Base64 according to encoding. |
| `encoding` | JSON string | utf8 (default) or base64. |
| `overwrite` | JSON boolean | Default false; true is required to replace a file. |
| `expectedSha256` | JSON string | Current hash from files/read; required when overwriting. |

## Response

JSON {path,bytes,sha256}. A missing/changed overwrite target returns 409.

## Example

```sh
curl --fail-with-body "$DEVICE_URL/files/write" \
  -H 'Content-Type: application/json' \
  -d '{"path":"Demo.cso/main.js","content":"console.log(\"Ready\");\n","overwrite":false}'
```

## Notes

Maximum decoded file size: 8 MiB. Never delete/recreate a file to bypass an edit conflict.

Paths are relative to Scripts. Absolute paths, parent traversal and symlink traversal are rejected. [File rules](https://mcp.applesauceos.com/doc/http-guide.md#files-and-project-directories) apply to every file endpoint.

Check the HTTP status and any JSON error. [HTTP workflows and error handling](https://mcp.applesauceos.com/doc/http-guide.md) explain shared limits. [All endpoints](https://mcp.applesauceos.com/doc/http.md).