#Volume HTTP

Use direct Volume file operations to operate on files in a Volume by volume ID, without mounting the Volume into a Sandbox first.

Start with the Go, Python, TypeScript SDKs, or the s0 CLI. The endpoint reference below is for advanced integrations and custom clients that need to call the HTTP and WebSocket API directly.

Base Model#

• Every path is resolved relative to the Volume root.
• Use absolute logical paths such as /docs/readme.txt.
• Read operations use sandboxvolumefile:read.
• Write, move, mkdir, and delete operations use sandboxvolumefile:write.

SDK and CLI Quick Start#

Use these helpers for normal direct Volume file workflows.

go
ctx := context.Background()
volumeID := "vol_abc123"

_, err := client.MkdirVolumeFile(ctx, volumeID, "/docs", true)
if err != nil {
  log.Fatal(err)
}

_, err = client.WriteVolumeFile(ctx, volumeID, "/docs/readme.txt", []byte("Hello from Volume HTTP"))
if err != nil {
  log.Fatal(err)
}

summary, err := client.UploadVolumeDirectory(ctx, volumeID, "./dist", "/apps/current")
if err != nil {
  log.Fatal(err)
}
fmt.Printf("uploaded files=%d bytes=%d\n", summary.Files, summary.Bytes)

data, err := client.ReadVolumeFile(ctx, volumeID, "/docs/readme.txt")
if err != nil {
  log.Fatal(err)
}
fmt.Println(string(data))

info, err := client.StatVolumeFile(ctx, volumeID, "/docs/readme.txt")
if err != nil {
  log.Fatal(err)
}
fmt.Printf("size=%d mode=%s\n", info.Size, info.Mode)

entries, err := client.ListVolumeFiles(ctx, volumeID, "/docs")
if err != nil {
  log.Fatal(err)
}
fmt.Printf("entries=%d\n", len(entries))

_, err = client.MoveVolumeFile(ctx, volumeID, "/docs/readme.txt", "/docs/readme-old.txt")
if err != nil {
  log.Fatal(err)
}

_, err = client.DeleteVolumeFile(ctx, volumeID, "/docs/readme-old.txt")
if err != nil {
  log.Fatal(err)
}

Client Method Mapping#

Directory Upload#

Use directory upload for build artifacts, framework bundles, and other multi-file trees.

go
summary, err := client.UploadVolumeDirectory(ctx, volumeID, "./dist", "/apps/current")
if err != nil {
  log.Fatal(err)
}

fmt.Printf("uploaded files=%d dirs=%d symlinks=%d bytes=%d\n",
  summary.Files,
  summary.Directories,
  summary.Symlinks,
  summary.Bytes,
)

FileInfo#

Write File#

Write binary content to a file. Creates parent directories automatically when needed.

Request Body#

Raw bytes. For SDK and CLI usage, see the quick start and method mapping above.

Read File#

Read a file from a Volume.

By default the response body is raw bytes.

If you set Accept: application/json, the API returns a base64 JSON payload instead:

Example response:

json
{
    "success": true,
    "data": {
        "content": "SGVsbG8sIFZvbHVtZSEK",
        "encoding": "base64"
    }
}

Create Directory#

Create a directory with the same endpoint used for file writes.

For SDK and CLI usage, see the create-directory row in the method mapping above.

Stat Path#

Return metadata for a file or directory.

Example response:

json
{
    "success": true,
    "data": {
        "name": "readme.txt",
        "path": "/docs/readme.txt",
        "type": "file",
        "size": 15,
        "mode": "0644",
        "mod_time": "2026-04-03T10:00:00Z",
        "is_link": false
    }
}

List Directory#

List the direct children of a directory.

Example response:

json
{
    "success": true,
    "data": {
        "entries": [
            {
                "name": "readme.txt",
                "path": "/docs/readme.txt",
                "type": "file",
                "size": 15,
                "mode": "0644",
                "mod_time": "2026-04-03T10:00:00Z",
                "is_link": false
            },
            {
                "name": "images",
                "path": "/docs/images",
                "type": "dir",
                "size": 0,
                "mode": "0755",
                "mod_time": "2026-04-03T10:00:00Z",
                "is_link": false
            }
        ]
    }
}

Move or Rename#

Move or rename a file or directory.

Request Body#

For SDK and CLI usage, see the move-or-rename row in the method mapping above.

Delete File or Directory#

Delete a file or recursively delete a directory.

For SDK and CLI usage, see the delete-path row in the method mapping above.

Watch for Changes#

Watch a path for file events over WebSocket.

WebSocket Protocol#

After connecting, send JSON messages to subscribe and unsubscribe.

Client messages:

Server messages:

Event names currently include:

• create
• write
• remove
• rename
• chmod
• invalidate

Client Watch Examples#

go
watchCtx, cancel := context.WithCancel(context.Background())
defer cancel()

events, errs, unsubscribe, err := client.WatchVolumeFiles(watchCtx, volumeID, "/docs", true)
if err != nil {
  log.Fatal(err)
}
defer func() { _ = unsubscribe() }()

for {
  select {
  case ev, ok := <-events:
      if !ok {
          return
      }
      if ev.Type == "event" {
          fmt.Printf("%s %s\n", ev.Event, ev.Path)
      }
  case err, ok := <-errs:
      if ok && err != nil {
          log.Fatal(err)
      }
      return
  }
}

Notes#

• GET /files, GET /stat, and GET /list require a path query parameter.
• POST /files with mkdir=true creates directories instead of writing file content.
• Directory uploads use a tar stream internally and are not atomic. Deployment flows that require rollback should import into a fresh Volume or snapshot before switching traffic.
• DELETE /files is recursive for directories.
• File size is currently capped by the direct HTTP handler. Large transfer workflows should prefer snapshots when appropriate.

Next Steps#