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

# POST /v1/capsules/{id}/files/write — Upload a file

> POST /v1/capsules/{id}/files/write — Upload a file to a specific path inside a capsule. Use multipart/form-data with the path and file fields.

Use this endpoint to write a file to an absolute path inside a running capsule. The request uses `multipart/form-data` with two fields: the destination path and the file content. For files larger than a few megabytes, use the streaming variant to avoid buffering the entire payload in memory.

## Endpoint

```http theme={null}
POST https://app.wrenn.dev/api/v1/capsules/{id}/files/write
```

## Authentication

<ParamField header="X-API-Key" type="string" required>
  Your team's API key. Pass the full `wrn_...` key value.
</ParamField>

## Path parameters

<ParamField path="id" type="string" required>
  The ID of the capsule to write the file into. The capsule must be in the `running` state.
</ParamField>

## Request body

Content-Type: `multipart/form-data`

<ParamField body="path" type="string" required>
  Absolute destination path inside the capsule filesystem, e.g. `"/app/main.py"`. The parent directory must already exist.
</ParamField>

<ParamField body="file" type="binary" required>
  The file content to upload.
</ParamField>

### Example request

```bash theme={null}
curl -X POST https://app.wrenn.dev/api/v1/capsules/cl-abc123/files/write \
  -H "X-API-Key: wrn_your_api_key_here" \
  -F "path=/app/main.py" \
  -F "file=@./main.py"
```

## Response

Returns `204 No Content` on success. No body is returned.

## Streaming upload

For large files, use the streaming endpoint instead. It streams the payload directly to the capsule without buffering it in memory on the server:

```http theme={null}
POST https://app.wrenn.dev/api/v1/capsules/{id}/files/stream/write
```

The request format is identical — `multipart/form-data` with `path` and `file` fields. The response is also `204 No Content` on success.

```bash theme={null}
curl -X POST https://app.wrenn.dev/api/v1/capsules/cl-abc123/files/stream/write \
  -H "X-API-Key: wrn_your_api_key_here" \
  -F "path=/data/large-dataset.csv" \
  -F "file=@./large-dataset.csv"
```

<Tip>
  Use the streaming endpoint for files larger than a few MB. The standard endpoint buffers the whole file before writing; the streaming endpoint does not.
</Tip>

## Python SDK

```python theme={null}
from wrenn import Capsule

with Capsule(wait=True) as capsule:
    # Write a string directly
    capsule.files.write("/app/main.py", "print('hello world')")

    # Upload a file using the streaming endpoint (recommended for large files)
    def chunks():
        with open("large-dataset.csv", "rb") as f:
            while chunk := f.read(64 * 1024):
                yield chunk

    capsule.files.upload_stream("/data/large-dataset.csv", chunks())
```

## Error responses

| Status                  | Meaning                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `409 Conflict`          | The capsule is not in the `running` state. Resume or start the capsule first.          |
| `413 Content Too Large` | The file exceeds the maximum allowed size. Use the streaming endpoint for large files. |