Skip to main content
Use this endpoint to read a file from an absolute path inside a running capsule. The response is raw binary content with Content-Type: application/octet-stream. For large files, use the streaming variant to avoid loading the entire file into memory at once.

​
Endpoint

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

​
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 read the file from. The capsule must be in the running state.

​
Request body

​
path
string
required
Absolute path to the file inside the capsule, e.g. "/app/output.json".

​
Example request

curl -X POST https://app.wrenn.dev/api/v1/capsules/cl-abc123/files/read \
  -H "X-API-Key: wrn_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"path": "/app/output.json"}' \
  --output output.json

{"path": "/app/output.json"}

​
Response

Returns 200 OK with raw binary file content. The Content-Type header is application/octet-stream.

​
Streaming download

For large files, use the streaming endpoint instead. It returns the file content using chunked transfer encoding, so you can process or write the data incrementally without buffering the whole file: 
POST https://app.wrenn.dev/api/v1/capsules/{id}/files/stream/read
The request body is identical — a JSON object with a path field. 
curl -X POST https://app.wrenn.dev/api/v1/capsules/cl-abc123/files/stream/read \
  -H "X-API-Key: wrn_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"path": "/data/large-output.bin"}' \
  --output large-output.bin
Use the streaming endpoint for large files to avoid loading the entire response into memory before writing it to disk.

​
Python SDK

from wrenn import Capsule

with Capsule(wait=True) as capsule:
    # Read file content as a decoded string
    content = capsule.files.read("/app/output.json")
    print(content)

    # Read file content as raw bytes
    data = capsule.files.read_bytes("/app/image.png")

    # Stream a large file to disk without buffering
    with open("large-output.bin", "wb") as f:
        for chunk in capsule.files.download_stream("/data/large-output.bin"):
            f.write(chunk)

​
Error responses

StatusMeaning
404 Not FoundThe capsule does not exist, or the specified path does not exist inside the capsule.
409 ConflictThe capsule is not in the running state. Resume or start the capsule first.