Skip to main content
POST
/
sandboxes
/
{sandbox_id}
/
files
/
watch
Watch Directory
curl --request POST \
  --url https://api.declaw.ai/sandboxes/{sandbox_id}/files/watch \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "path": "<string>"
}
'
Registers a filesystem watcher on the specified directory and streams change events to the client using Server-Sent Events (SSE). Events are emitted when files are created, modified, or deleted under the watched path.
Full SSE streaming for file watch events is in progress. The current release returns an empty {} body. The endpoint signature and request format are stable and will be updated to return a live event stream in an upcoming release.

​
Path Parameters

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

​
Request Body

​
path
string
required
Absolute path of the directory to watch inside the sandbox.Example: "/home/user/output"

​
Response

When streaming is fully implemented, the response will have Content-Type: text/event-stream and emit events with this format: 
event: change
data: {"type":"create","path":"/home/user/output/result.csv"}

event: change
data: {"type":"modify","path":"/home/user/output/result.csv"}

event: change
data: {"type":"delete","path":"/home/user/output/old.csv"}
Currently returns {}.

​
Example

curl -X POST https://api.declaw.ai/sandboxes/sbx-a1b2c3d4/files/watch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{ "path": "/home/user/output" }' \
  --no-buffer

​
Error Responses

StatusCause
401Missing or invalid API key
404Sandbox not found
503Sandbox has no VM