Summary

The bridge/worker/README.md API reference documents two file-operation endpoints with the wrong HTTP verb and wrong URL pattern. The README shows POST /v1/sandbox/:id/read (JSON body {"path": "..."}) and POST /v1/sandbox/:id/write (multipart form), but the actual implementation in packages/sandbox/src/bridge/routes.ts and the OpenAPI schema in packages/sandbox/src/bridge/openapi.ts both use GET /v1/sandbox/:id/file/* (path in URL, returns octet-stream) and PUT /v1/sandbox/:id/file/* (path in URL, raw body). A developer following the README will receive 405 Method Not Allowed and waste time debugging a route that does not exist.

What I observed

README (bridge/worker/README.md, lines 88–98 and 148–169) — stale:

| read()  | POST /v1/sandbox/:id/read  | Read a file from the workspace  |
| write() | POST /v1/sandbox/:id/write | Write a file into the workspace |

# README example for read — will 405:
curl -X POST http://localhost:8787/v1/sandbox/mfrggzdfmy2tqnrz/read \
  -H "Content-Type: application/json" \
  -d '{"path": "/workspace/main.py"}'

# README example for write — will 405:
curl -X POST http://localhost:8787/v1/sandbox/mfrggzdfmy2tqnrz/write \
  -F "path=/workspace/main.py" \
  -F "file=@main.py"

Actual implementation (packages/sandbox/src/bridge/routes.ts, lines 491 and 549):

// GET /sandbox/:id/file/*
app.get(`${apiPrefix}/sandbox/:id/file/*`, async (c) => { ... });

// PUT /sandbox/:id/file/*
app.put(`${apiPrefix}/sandbox/:id/file/*`, async (c) => { ... });

OpenAPI schema (packages/sandbox/src/bridge/openapi.ts, line 382) also matches actual routes:

GET  /v1/sandbox/{id}/file/{path}   — operationId: readFile
PUT  /v1/sandbox/{id}/file/{path}   — operationId: writeFile

The correct curl invocations (inferred from the OpenAPI schema examples) are:

# Read
curl -X GET https://$HOST/v1/sandbox/my-sandbox/file/workspace/main.py \
  -H "Authorization: Bearer $SANDBOX_API_KEY"

# Write
curl -X PUT https://$HOST/v1/sandbox/my-sandbox/file/workspace/main.py \
  -H "Authorization: Bearer $SANDBOX_API_KEY" \
  --data-binary @main.py

Suggested fix

Update bridge/worker/README.md:

1. In the Sandbox Interface table (around line 92–93), change:

   • POST /v1/sandbox/:id/read → GET /v1/sandbox/:id/file/*
   • POST /v1/sandbox/:id/write → PUT /v1/sandbox/:id/file/*

2. Replace the POST /v1/sandbox/:id/read section (lines 148–158) with a GET /v1/sandbox/:id/file/:path section using the correct verb, URL pattern, and curl example (path in URL, no JSON body).

3. Replace the POST /v1/sandbox/:id/write section (lines 161–169) with a PUT /v1/sandbox/:id/file/:path section using the correct verb, URL pattern, and curl example (raw binary body or -T flag).

The OpenAPI schema served at GET /v1/openapi.json already reflects the correct routes and can be used as the authoritative reference.

Notes

The Security section of the README (line 449) mentions /read and /write in the workspace containment note — this should be updated to /file/* as well for consistency.