> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapengine.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Write File

> Write or create a file in the session workspace. Parents are created automatically.

## Overview

Creates or overwrites a file in the session's workspace with base64-encoded content. Parent directories are created automatically. Paths must be relative to the workspace root (no leading `/`, no `..`, no NUL byte, up to 4096 bytes).

## Path Parameters

<ParamField path="id" type="string" required={true}>
  Browser session ID (UUID).
</ParamField>

## Body

<ParamField body="path" type="string" required={true}>
  Workspace-relative path, e.g. `a/b/c.txt`.
</ParamField>

<ParamField body="content" type="string" required={true}>
  Base64-encoded file content.
</ParamField>

<ParamField body="mode" type="integer" default="0644">
  Unix mode (octal). Applied after write.
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.scrapengine.io/api/v1/browser/sessions/baa3f390-fa6e-4a24-b84a-a575a5f3a9c7/fs/file" \
    -H "Authorization: Bearer $SCRAPENGINE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "path": "notes/todo.txt",
      "content": "SGVsbG8gV29ybGQ=",
      "mode": 420
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.scrapengine.io/api/v1/browser/sessions/baa3f390-fa6e-4a24-b84a-a575a5f3a9c7/fs/file",
    {
      method: "PUT",
      headers: {
        "Authorization": `Bearer ${process.env.SCRAPENGINE_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        path: "notes/todo.txt",
        content: Buffer.from("Hello World").toString("base64"),
      }),
    },
  );
  ```
</CodeGroup>

## Response

### Success Response (201)

<ResponseField name="path" type="string">
  The written workspace-relative path.
</ResponseField>

<ResponseField name="bytes" type="integer">
  Decoded byte length of the written content.
</ResponseField>

**Example Response:**

```json theme={null}
{
  "path": "notes/todo.txt",
  "bytes": 11
}
```

### Error Responses

| Status | Description                                                     |
| ------ | --------------------------------------------------------------- |
| `400`  | Invalid body — bad path, non-base64 content, or unknown fields. |
| `401`  | Unauthorized — invalid or missing API key.                      |
| `404`  | Session not found.                                              |
| `413`  | Decoded content exceeds the maximum write size.                 |