These advanced file operations extend the core Files API with IDE-oriented capabilities: recursive tree listing, atomic batch writes, and a live file-change event stream.

Base path: /api/v1/sandboxes/{id}/files

Endpoints

File Tree

GET /api/v1/sandboxes/{id}/files/tree

Returns a recursive directory listing up to a configurable depth. Useful for populating an IDE file-explorer panel.

Auth

Authorization: Bearer msk_...

Query Parameters

Response - 200 OK

{
  "data": {
    "path": "/workspace",
    "type": "directory",
    "children": [
      {
        "name": "src",
        "path": "/workspace/src",
        "type": "directory",
        "children": [
          {
            "name": "index.ts",
            "path": "/workspace/src/index.ts",
            "type": "file",
            "size": 1842,
            "modified_at": "2026-05-26T09:12:01Z"
          }
        ]
      },
      {
        "name": "package.json",
        "path": "/workspace/package.json",
        "type": "file",
        "size": 512,
        "modified_at": "2026-05-25T18:00:00Z"
      }
    ]
  }
}

Batch Write

POST /api/v1/sandboxes/{id}/files/write-many

Writes multiple files in a single request. All writes are applied atomically from the guest’s perspective - either all succeed or an error is returned for the failing file.

Request Body

{
  "files": [
    {
      "path": "/workspace/src/index.ts",
      "content": "export const hello = () => 'world';\n",
      "encoding": "utf8"
    },
    {
      "path": "/workspace/src/utils.ts",
      "content": "ZXhwb3J0IGZ1bmN0aW9uIG5vb3AoKSB7fQo=",
      "encoding": "base64"
    }
  ]
}

Response - 200 OK

{
  "data": {
    "written": 2,
    "paths": [
      "/workspace/src/index.ts",
      "/workspace/src/utils.ts"
    ]
  }
}

Errors

File Watch (SSE)

GET /api/v1/sandboxes/{id}/files/watch

Streams file-system change events as SSE. Useful for syncing editor state in real time.

Auth

Authorization: Bearer msk_...

(Browser EventSource cannot set this header - use a server-side client or a scoped session token.)

Query Parameters

Response - 200 OK (text/event-stream)

id: wev_001
event: file.changed
data: {"path":"/workspace/src/index.ts","event":"modified","ts":"2026-05-26T10:14:23Z"}

id: wev_002
event: file.changed
data: {"path":"/workspace/src/new-file.ts","event":"created","ts":"2026-05-26T10:14:24Z"}

: heartbeat

Event values for data.event:

Examples