Points de terminaison Sandbox API

Référence complète des points de terminaison REST des sandboxes, incluant la récupération de transcript, la messagerie de suivi, les données de l’explorateur de fichiers, l’inspection de diff git et les contrôles du serveur de prévisualisation.

10 min lire
apisandboxese2b

Les sandboxes sont les environnements d’exécution derrière la page de détail de run. Ces points de terminaison exposent tout ce que le dashboard peut actuellement lire ou faire avec la sandbox active d’un run : historique de transcript, chat de suivi, navigation de fichiers, diffs git et contrôles du serveur de prévisualisation.

Points de terminaison de lecture

GET /api/v1/sandboxes/list

Liste les sandboxes du projet authentifié.

Paramètres de query :

  • runId (optionnel) - uniquement les sandboxes appartenant à un run
  • limit (optionnel, max 100)
curl -H "Authorization: Bearer cc_live_..."   "https://<deployment>.convex.site/api/v1/sandboxes/list?runId=r_..."

GET /api/v1/sandboxes/get

Récupère une seule sandbox par ID.

GET /api/v1/sandboxes/messages

Récupère l’historique complet de conversation de la sandbox. Ce point de terminaison inclut désormais les lignes d’événements de transcript Pi par message assistant, afin que les clients API puissent reconstruire exactement la timeline de transcript affichée dans l’UI.

Paramètres de query :

  • id (requis) - ID du document sandbox
  • includeTranscriptEvents (optionnel, par défaut 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 chronologique en append-only des événements de cycle de vie de la sandbox (clone, sandbox-create, install, setup-script, agent-cli). Utilisez ceci quand /sandboxes/messages renvoie une liste vide et que vous devez savoir pourquoi la sandbox n’a jamais produit de transcript - par exemple, une erreur de clone, un échec de boot E2B, ou un crash de script de setup.

Paramètres de query :

  • id (requis) - ID du document sandbox
  • order (optionnel) - asc (par défaut) ou 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'"
      }
    }
  ]
}

Plafonné à 500 événements par sandbox. Types d’événements :clone-*, sandbox-create-*,install-*, setup-script-*,agent-cli-*, plus un error générique.

GET /api/v1/sandboxes/files

Liste les fichiers pour l’explorateur de sandbox. Si path est omis, l’API détecte automatiquement la racine du projet et la renvoie dans data.rootPath.

  • id (requis) - ID de la sandbox
  • path (optionnel) - répertoire à inspecter

GET /api/v1/sandboxes/file

Lit un seul fichier depuis l’explorateur de sandbox.

  • id (requis)
  • path (requis)

La réponse inclut les flags binary et truncated quand applicable, à l’identique du comportement du dashboard.

GET /api/v1/sandboxes/diff

Renvoie le diff git, le statut porcelain et le résumé lisible utilisés par l’onglet «Diff» du détail de run.

GET /api/v1/sandboxes/dev-server

Vérifie si un serveur de prévisualisation écoute déjà sur un port et récupère l’URL de prévisualisation publique.

  • id (requis)
  • port (optionnel)

Points de terminaison d’écriture / action

POST /api/v1/sandboxes/send-message

Envoie un message de suivi à une sandbox en cours d’exécution, exactement comme la boîte de chat sur la page de détail de run.

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

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

Démarre le serveur de prévisualisation utilisé par l’onglet «Preview».

Champs du body :

  • sandboxId (requis)
  • mode (optionnel) - production ou development
  • command (optionnel) - commande de dev, ou une commande de production combinée comme npm run build && npm run start
  • port (optionnel)

La réponse inclut :

  • started
  • mode
  • url
  • steps.install, steps.build, steps.start pour le mode production
  • alreadyRunning quand un serveur est déjà présent

POST /api/v1/sandboxes/rename

Renomme une sandbox.

POST /api/v1/sandboxes/delete

Supprime une sandbox (soft-delete).

POST /api/v1/sandboxes/restore

Restaure une sandbox supprimée en soft-delete.

POST /api/v1/sandboxes/permanent-delete

Supprime définitivement une sandbox.

Correspondance avec l’UI de détail de run

  • Panneau transcript : /sandboxes/messages
  • Debug d’échec de setup : /sandboxes/events
  • Chat de suivi : /sandboxes/send-message
  • Onglet Files : /sandboxes/files + /sandboxes/file
  • Onglet Diff : /sandboxes/diff
  • Onglet Preview : /sandboxes/dev-server + /sandboxes/dev-server/start