Sandbox API Endpoints

Sandboxes are the execution environments behind the run detail page. These endpoints expose everything the dashboard can currently read or do with a run's active sandbox: transcript history, follow-up chat, file browsing, git diffs, and preview-server controls.

Read Endpoints

GET /api/v1/sandboxes/list

List sandboxes for the authenticated project.

Query parameters:

• runId (optional) - only sandboxes belonging to one run
• limit (optional, max 100)

curl -H "Authorization: Bearer cc_live_..."   "https://<deployment>.convex.site/api/v1/sandboxes/list?runId=r_..."

GET /api/v1/sandboxes/get

Retrieve a single sandbox by ID.

GET /api/v1/sandboxes/messages

Retrieve the full sandbox conversation history. This endpoint now includes Pi transcript event rows per assistant message so API clients can reconstruct the exact transcript timeline shown in the UI.

Query parameters:

• id (required) - sandbox document ID
• includeTranscriptEvents (optional, default true)

{
  "data": [
    {
      "id": "msg_...",
      "_id": "msg_...",
      "role": "assistant",
      "content": "Final answer",
      "streamLog": "...",
      "status": "completed",
      "startedAt": 1705312900000,
      "completedAt": 1705312910000,
      "timestamp": 1705312910000,
      "piTranscriptEvents": [
        { "seq": 1, "payload": "{"kind":"tool_call",...}", "createdAt": 1705312900100 }
      ]
    }
  ]
}

GET /api/v1/sandboxes/events

Append-only chronological timeline of sandbox lifecycle events (clone, sandbox-create, install, setup-script, agent-cli). Use this when /sandboxes/messages returns an empty list and you need to know why the sandbox never produced a transcript - e.g. a clone error, an E2B boot failure, or a setup script crash.

Query parameters:

• id (required) - sandbox document ID
• order (optional) - asc (default) or desc

{
  "data": [
    {
      "id": "evt_...",
      "_id": "evt_...",
      "_creationTime": 1714000000000,
      "sandboxId": "sbx_...",
      "projectId": "prj_...",
      "type": "clone-error",
      "ts": 1714000000123,
      "payload": {
        "stage": "clone",
        "durationMs": 8421,
        "exitCode": 128,
        "stderrTail": "fatal: could not read Username for 'https://github.com'"
      }
    }
  ]
}

Capped at 500 events per sandbox. Event types:clone-*, sandbox-create-*,install-*, setup-script-*,agent-cli-*, plus a generic error.

GET /api/v1/sandboxes/files

List files for the sandbox explorer. If path is omitted, the API auto-detects the project root and returns it indata.rootPath.

• id (required) - sandbox ID
• path (optional) - directory to inspect

GET /api/v1/sandboxes/file

Read a single file from the sandbox explorer.

• id (required)
• path (required)

The response includes binary and truncatedflags when applicable, matching the dashboard behavior.

GET /api/v1/sandboxes/diff

Return the git diff, porcelain status, and human-readable summary used by the run detail “Diff” tab.

GET /api/v1/sandboxes/dev-server

Check whether a preview server is already listening on a port and get the public preview URL.

• id (required)
• port (optional)

Write / Action Endpoints

POST /api/v1/sandboxes/send-message

Send a follow-up message to a running sandbox, exactly like the chat box on the run detail page.

{ "sandboxId": "...", "message": "Please also update the docs." }

POST /api/v1/sandboxes/dev-server/start

Start the preview server used by the “Preview” tab.

Body fields:

• sandboxId (required)
• mode (optional) - production or development
• command (optional) - dev command, or a combined production command like npm run build && npm run start
• port (optional)

Response includes:

• started
• mode
• url
• steps.install, steps.build, steps.start for production mode
• alreadyRunning when a server is already present

POST /api/v1/sandboxes/rename

Rename a sandbox.

POST /api/v1/sandboxes/delete

Soft-delete a sandbox.

POST /api/v1/sandboxes/restore

Restore a soft-deleted sandbox.

POST /api/v1/sandboxes/permanent-delete

Permanently delete a sandbox.

How This Maps to the Run Detail UI

• Transcript panel: /sandboxes/messages
• Setup-failure debugging: /sandboxes/events
• Follow-up chat: /sandboxes/send-message
• Files tab: /sandboxes/files + /sandboxes/file
• Diff tab: /sandboxes/diff
• Preview tab: /sandboxes/dev-server + /sandboxes/dev-server/start