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

# Watch Directory

> Watch a directory for filesystem changes via Server-Sent Events.

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.

<Note>
  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.
</Note>

## Path Parameters

<ParamField path="sandbox_id" type="string" required>
  The sandbox identifier. Format: `sbx-<8 chars>`.
</ParamField>

## Request Body

<ParamField body="path" type="string" required>
  Absolute path of the directory to watch inside the sandbox.

  Example: `"/home/user/output"`
</ParamField>

## 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

<CodeGroup>
  ```bash cURL theme={null}
  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
  ```

  ```python Python theme={null}
  from declaw import Sandbox

  sbx = Sandbox.connect("sbx-a1b2c3d4", api_key="YOUR_API_KEY", domain="api.declaw.ai")

  # watch_dir returns a WatchHandle. Drain buffered events with get_new_events().
  handle = sbx.files.watch_dir("/home/user/output")
  for event in handle.get_new_events():
      print(event.type, event.path)
  handle.stop()
  ```

  ```typescript TypeScript theme={null}
  import { Sandbox } from "@declaw/sdk";

  const sbx = await Sandbox.connect("sbx-a1b2c3d4", {
    apiKey: "YOUR_API_KEY",
    domain: "api.declaw.ai",
  });

  const handle = await sbx.files.watchDir("/home/user/output");
  for (const event of handle.getNewEvents()) {
    console.log(event.type, event.path);
  }
  handle.stop();
  ```
</CodeGroup>

## Error Responses

| Status | Cause                      |
| ------ | -------------------------- |
| `401`  | Missing or invalid API key |
| `404`  | Sandbox not found          |
| `503`  | Sandbox has no VM          |