Endpoint Sandbox API

Riferimento completo per gli endpoint REST delle sandbox, incluso il recupero dei transcript, la messaggistica di follow-up, i dati dell’esploratore file, l’ispezione dei diff git e i controlli del server di anteprima.

10 min letto
apisandboxese2b

Le sandbox sono gli ambienti di esecuzione dietro la pagina di dettaglio run. Questi endpoint espongono tutto ciò che la dashboard può attualmente leggere o fare con la sandbox attiva di un run: cronologia transcript, chat di follow-up, navigazione file, diff git e controlli del server di anteprima.

Endpoint di lettura

GET /api/v1/sandboxes/list

Elenca le sandbox del progetto autenticato.

Parametri di query:

  • runId (opzionale) - solo le sandbox appartenenti a un run
  • limit (opzionale, max 100)
curl -H "Authorization: Bearer cc_live_..."   "https://<deployment>.convex.site/api/v1/sandboxes/list?runId=r_..."

GET /api/v1/sandboxes/get

Recupera una singola sandbox per ID.

GET /api/v1/sandboxes/messages

Recupera la cronologia completa di conversazione della sandbox. Questo endpoint ora include le righe di eventi transcript Pi per ogni messaggio assistant, così i client API possono ricostruire esattamente la timeline del transcript mostrata nell’UI.

Parametri di query:

  • id (obbligatorio) - ID del documento sandbox
  • includeTranscriptEvents (opzionale, predefinito 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

Timeline cronologica append-only degli eventi del ciclo di vita della sandbox (clone, sandbox-create, install, setup-script, agent-cli). Usa questo quando /sandboxes/messages restituisce una lista vuota e devi capire perché la sandbox non ha mai prodotto un transcript - ad esempio un errore di clone, un fallimento di boot E2B, o un crash dello script di setup.

Parametri di query:

  • id (obbligatorio) - ID del documento sandbox
  • order (opzionale) - asc (predefinito) o 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'"
      }
    }
  ]
}

Limitato a 500 eventi per sandbox. Tipi di evento:clone-*, sandbox-create-*,install-*, setup-script-*,agent-cli-*, più un error generico.

GET /api/v1/sandboxes/files

Elenca i file per l’esploratore della sandbox. Se path viene omesso, l’API rileva automaticamente la root del progetto e la restituisce in data.rootPath.

  • id (obbligatorio) - ID della sandbox
  • path (opzionale) - directory da ispezionare

GET /api/v1/sandboxes/file

Legge un singolo file dall’esploratore della sandbox.

  • id (obbligatorio)
  • path (obbligatorio)

La risposta include i flag binary e truncated quando applicabili, in linea con il comportamento della dashboard.

GET /api/v1/sandboxes/diff

Restituisce il diff git, lo stato porcelain e il riepilogo leggibile usati dal tab «Diff» del dettaglio run.

GET /api/v1/sandboxes/dev-server

Verifica se un server di anteprima è già in ascolto su una porta e ottiene l’URL di anteprima pubblico.

  • id (obbligatorio)
  • port (opzionale)

Endpoint di scrittura / azione

POST /api/v1/sandboxes/send-message

Invia un messaggio di follow-up a una sandbox in esecuzione, esattamente come la casella di chat nella pagina di dettaglio run.

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

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

Avvia il server di anteprima usato dal tab «Preview».

Campi del body:

  • sandboxId (obbligatorio)
  • mode (opzionale) - production o development
  • command (opzionale) - comando dev, oppure un comando di produzione combinato come npm run build && npm run start
  • port (opzionale)

La risposta include:

  • started
  • mode
  • url
  • steps.install, steps.build, steps.start per la modalità produzione
  • alreadyRunning quando un server è già presente

POST /api/v1/sandboxes/rename

Rinomina una sandbox.

POST /api/v1/sandboxes/delete

Elimina (soft-delete) una sandbox.

POST /api/v1/sandboxes/restore

Ripristina una sandbox eliminata con soft-delete.

POST /api/v1/sandboxes/permanent-delete

Elimina definitivamente una sandbox.

Corrispondenza con l’UI di dettaglio run

  • Pannello transcript: /sandboxes/messages
  • Debug di errori di setup: /sandboxes/events
  • Chat di follow-up: /sandboxes/send-message
  • Tab Files: /sandboxes/files + /sandboxes/file
  • Tab Diff: /sandboxes/diff
  • Tab Preview: /sandboxes/dev-server + /sandboxes/dev-server/start