Skip to main content
Sandbox endpoints provide lifecycle management for isolated development environments where code is executed.

​
POST /api/sandbox/create

Creates a new sandbox instance.

​
Request body

No request body required.

​
Response

​
success
boolean
Whether the sandbox was created successfully
​
sandboxId
string
Unique identifier for the created sandbox
​
url
string
Preview URL where the sandbox can be accessed
​
error
string
Error message if success is false

​
Error codes

​
500
Internal Server Error
Failed to create sandbox

​
Example request

curl -X POST https://your-domain.com/api/sandbox/create

​
Example response

{
  "success": true,
  "sandboxId": "sb_abc123xyz",
  "url": "https://abc123xyz.preview.example.com"
}

​
GET /api/sandbox/status

Checks if a sandbox is alive and returns its information.

​
Query parameters

​
sandboxId
string
The sandbox ID to check. If omitted, checks the currently active sandbox

​
Response

​
success
boolean
Whether the status check succeeded
​
isAlive
boolean
Whether the sandbox is currently running
​
sandboxId
string
The sandbox identifier
​
url
string
Preview URL for the sandbox
​
error
string
Error message if success is false

​
Error codes

​
404
Not Found
No active sandbox found
​
500
Internal Server Error
Failed to retrieve sandbox status

​
Example request

curl https://your-domain.com/api/sandbox/status?sandboxId=sb_abc123

​
Example response

{
  "success": true,
  "isAlive": true,
  "sandboxId": "sb_abc123",
  "url": "https://abc123.preview.example.com"
}

​
GET /api/sandbox/files

Retrieves the list of files in a sandbox.

​
Query parameters

​
sandboxId
string
The sandbox ID. If omitted, uses the currently active sandbox

​
Response

​
success
boolean
Whether the file list was retrieved successfully
​
files
array
Array of file paths as strings
​
error
string
Error message if success is false

​
Error codes

​
404
Not Found
No active sandbox found
​
500
Internal Server Error
Failed to retrieve file list

​
Example request

curl https://your-domain.com/api/sandbox/files?sandboxId=sb_abc123

​
Example response

{
  "success": true,
  "files": [
    "package.json",
    "src/App.tsx",
    "src/index.tsx",
    "src/components/Button.tsx",
    "public/index.html"
  ]
}

​
POST /api/sandbox/diagnostics

Runs diagnostic checks on a sandbox to verify its health and capabilities.

​
Request body

​
sandboxId
string
The sandbox ID to diagnose. If omitted, diagnoses the active sandbox

​
Response

Returns diagnostic results as JSON. The structure depends on the implementation of runSandboxDiagnostics.

​
Example request

curl -X POST https://your-domain.com/api/sandbox/diagnostics \
  -H "Content-Type: application/json" \
  -d '{"sandboxId": "sb_abc123"}'

​
Example response

{
  "sandboxId": "sb_abc123",
  "status": "healthy",
  "checks": {
    "filesystem": "ok",
    "network": "ok",
    "runtime": "ok"
  }
}

​
POST /api/sandbox/kill

Terminates a sandbox or all sandboxes.

​
Request body

​
sandboxId
string
The sandbox ID to terminate. If omitted, terminates all active sandboxes

​
Response

​
success
boolean
Whether the termination succeeded
​
error
string
Error message if success is false

​
Error codes

​
500
Internal Server Error
Failed to terminate sandbox

​
Example request (specific sandbox)

curl -X POST https://your-domain.com/api/sandbox/kill \
  -H "Content-Type: application/json" \
  -d '{"sandboxId": "sb_abc123"}'

​
Example request (all sandboxes)

curl -X POST https://your-domain.com/api/sandbox/kill

​
Example response

{
  "success": true
}

​
POST /api/packages/install

Installs npm packages in a sandbox.

​
Request body

​
packages
string[]
required
Array of package names to install (e.g., ["react", "lodash"])
​
sandboxId
string
The sandbox ID where packages should be installed. If omitted, uses the active sandbox

​
Response

​
success
boolean
Whether the installation succeeded
​
installedPackages
string[]
List of successfully installed packages
​
error
string
Error message if success is false

​
Error codes

​
400
Bad Request
Invalid JSON body or empty packages array
​
500
Internal Server Error
Failed to install packages

​
Example request

curl -X POST https://your-domain.com/api/packages/install \
  -H "Content-Type: application/json" \
  -d '{
    "packages": ["react-icons", "framer-motion"],
    "sandboxId": "sb_abc123"
  }'

​
Example response

{
  "success": true,
  "installedPackages": ["react-icons", "framer-motion"]
}

​
Sandbox lifecycle

A typical sandbox workflow:
  1. Create a sandbox using /api/sandbox/create
  2. Generate code with /api/generate/stream
  3. Apply the code using /api/apply/stream (includes package installation)
  4. Install additional packages via /api/packages/install if needed
  5. Check status via /api/sandbox/status to verify it’s running
  6. List files with /api/sandbox/files to inspect contents
  7. Terminate when done using /api/sandbox/kill
Sandboxes maintain state across requests using the sandboxId identifier.

Build docs developers (and LLMs) love

Get started for freeTalk to us