Skip to main content
PUT
/
sandboxes
/
{sandbox_id}
/
files
/
raw
Write File (Raw / Binary)
curl --request PUT \
  --url https://api.declaw.ai/sandboxes/{sandbox_id}/files/raw \
  --header 'Content-Type: <content-type>' \
  --header 'X-API-Key: <api-key>'
Streams the request body directly into a file on the sandbox disk without buffering in memory. Use this endpoint for any binary payload — images, archives, compiled artifacts, base64-decoded blobs — or for uploads larger than the 10 MiB JSON gateway cap. For UTF-8 text, the JSON POST /files endpoint is usually the simpler choice.

​
Path Parameters

​
sandbox_id
string
required
The sandbox identifier. Format: sbx-<8 chars>.

​
Query Parameters

​
path
string
required
Absolute path to write inside the sandbox. Parent directories are created automatically.Example: /home/user/image.png
​
username
string
Unix user to own the written file. Defaults to the envd default user.

​
Request Headers

​
Content-Type
string
required
Must be application/octet-stream.

​
Request Body

Raw bytes. Up to 500 MiB per request. The body is streamed to disk with a flat memory footprint on the orchestrator.

​
Response

{
  "path": "/home/user/image.png",
  "size": 4096
}

​
Example

curl -X PUT "https://api.declaw.ai/sandboxes/sbx-a1b2c3d4/files/raw?path=/home/user/image.png" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @image.png

​
When to use this vs. other endpoints

PayloadUse
UTF-8 text, < 10 MiBPOST /files (JSON)
Binary (any size up to 500 MiB)PUT /files/raw (this endpoint)
Very large payloads (hundreds of MB, GB-class)sbx.upload_url(path) / sbx.download_url(path) helpers

​
Error Responses

StatusCause
400Missing path query parameter
401Missing or invalid API key
404Sandbox not found
409Sandbox is paused — resume it before accessing files
410Sandbox has been killed
413Request body exceeds 500 MiB
502envd daemon unreachable
503Sandbox has no VM