Skip to main content
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

POST https://app.wrenn.dev/api/v1/capsules/{id}/files/write

​
Authentication

​
X-API-Key
string
required
Your team’s API key. Pass the full wrn_... key value.

​
Path parameters

​
id
string
required
The ID of the capsule to write the file into. The capsule must be in the running state.

​
Request body

Content-Type: multipart/form-data
​
path
string
required
Absolute destination path inside the capsule filesystem, e.g. "/app/main.py". The parent directory must already exist.
​
file
binary
required
The file content to upload.

​
Example request

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: 
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. 
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"
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.

​
Python SDK

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

StatusMeaning
409 ConflictThe capsule is not in the running state. Resume or start the capsule first.
413 Content Too LargeThe file exceeds the maximum allowed size. Use the streaming endpoint for large files.