Sandbox-API-Endpunkte

Vollständige Referenz für die Sandbox-REST-Endpunkte - inklusive Transkript-Abruf, Follow-up-Messaging, Datei-Explorer-Daten, Git-Diff-Inspektion und Preview-Server-Steuerung.

10 Min. Lesezeit
apisandboxese2b

Sandboxes sind die Ausführungsumgebungen hinter der Run-Detail-Seite. Diese Endpunkte stellen alles bereit, was das Dashboard derzeit mit der aktiven Sandbox eines Runs lesen oder tun kann: Transkriptverlauf, Follow-up-Chat, Dateibrowser, Git-Diffs und Preview-Server-Steuerung.

Lese-Endpunkte

GET /api/v1/sandboxes/list

Sandboxes für das authentifizierte Projekt auflisten.

Query-Parameter:

  • runId (optional) - nur Sandboxes eines bestimmten Runs
  • 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

Eine einzelne Sandbox per ID abrufen.

GET /api/v1/sandboxes/messages

Den vollständigen Sandbox-Konversationsverlauf abrufen. Dieser Endpunkt enthält jetzt auch Pi-Transcript-Event-Zeilen pro Assistant-Nachricht, sodass API-Clients die exakte Transkript-Timeline rekonstruieren können, die in der UI angezeigt wird.

Query-Parameter:

  • id (erforderlich) - Sandbox-Dokument-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 chronologische Timeline der Sandbox-Lifecycle-Events (clone, sandbox-create, install, setup-script, agent-cli). Verwenden Sie dies, wenn /sandboxes/messages eine leere Liste liefert und Sie wissen müssen, warum die Sandbox kein Transkript erzeugt hat - z. B. ein Clone-Fehler, ein E2B-Boot-Fehler oder ein Crash eines Setup-Skripts.

Query-Parameter:

  • id (erforderlich) - Sandbox-Dokument-ID
  • order (optional) - asc (Default) oder 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'"
      }
    }
  ]
}

Auf 500 Events pro Sandbox begrenzt. Event-Typen:clone-*, sandbox-create-*,install-*, setup-script-*,agent-cli-* sowie ein generischer error.

GET /api/v1/sandboxes/files

Dateien für den Sandbox-Explorer auflisten. Wenn path weggelassen wird, ermittelt die API automatisch das Projekt-Root und liefert es in data.rootPath zurück.

  • id (erforderlich) - Sandbox-ID
  • path (optional) - zu inspizierendes Verzeichnis

GET /api/v1/sandboxes/file

Eine einzelne Datei aus dem Sandbox-Explorer lesen.

  • id (erforderlich)
  • path (erforderlich)

Die Antwort enthält die Flags binary und truncated, wenn zutreffend, entsprechend dem Verhalten des Dashboards.

GET /api/v1/sandboxes/diff

Liefert den Git-Diff, den Porcelain-Status und die menschenlesbare Zusammenfassung, die im „Diff“-Tab der Run-Detail-Ansicht verwendet wird.

GET /api/v1/sandboxes/dev-server

Prüfen, ob ein Preview-Server bereits auf einem Port lauscht, und die öffentliche Preview-URL abrufen.

  • id (erforderlich)
  • port (optional)

Schreib-/Aktions-Endpunkte

POST /api/v1/sandboxes/send-message

Eine Follow-up-Nachricht an eine laufende Sandbox senden, genau wie die Chatbox auf der Run-Detail-Seite.

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

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

Den Preview-Server starten, der vom „Preview“-Tab verwendet wird.

Body-Felder:

  • sandboxId (erforderlich)
  • mode (optional) - production oder development
  • command (optional) - Dev-Command oder ein kombinierter Production-Command wie npm run build && npm run start
  • port (optional)

Die Antwort enthält:

  • started
  • mode
  • url
  • steps.install, steps.build, steps.start für den Production-Modus
  • alreadyRunning, wenn bereits ein Server vorhanden ist

POST /api/v1/sandboxes/rename

Eine Sandbox umbenennen.

POST /api/v1/sandboxes/delete

Eine Sandbox per Soft-Delete löschen.

POST /api/v1/sandboxes/restore

Eine per Soft-Delete gelöschte Sandbox wiederherstellen.

POST /api/v1/sandboxes/permanent-delete

Eine Sandbox dauerhaft löschen.

Zuordnung zur Run-Detail-UI

  • Transkript-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