Overview

Sandbox API prerequisites, endpoint assembly, authentication, available instance and template management APIs, and error responses.

The Sandbox API is compatible with the E2B protocol and provides sandbox instance lifecycle management, template management, and file upload. Control-plane requests are forwarded through the Bailian AI gateway.

Prerequisites

1. Activate Bailian and create an API Key.
2. Complete service authorization: first-time use of Sandbox requires SLR authorization. See Quick Start.
3. Get your workspace ID: view it in the dropdown at the top-right of the Bailian console, in the form {workspace_id}.

Endpoint

The API base URL is assembled from the workspace and region:

https://{workspace_id}.{region}.maas.aliyuncs.com/api/v1/agentstudio/sandbox

• workspace_id: workspace ID
• region: region ID, currently only cn-beijing

Available APIs

Instance Management

Capability	Method	Path
Create instance	POST	/sandboxes
List instances	GET	/v2/sandboxes
Get instance	GET	/sandboxes/{sandboxID}
Connect to instance	POST	/sandboxes/{sandboxID}/connect
Pause instance	POST	/sandboxes/{sandboxID}/pause
Resume instance	POST	/sandboxes/{sandboxID}/resume
Release instance	DELETE	/sandboxes/{sandboxID}

Template Management

Capability	Method	Path
Create template	POST	/v3/templates
List templates	GET	/v2/templates
Get template	GET	/templates/{templateCode}
Update template	PUT	/templates/{templateCode}
Get build status	GET	/templates/{templateCode}/builds/{buildID}/status
Delete template	DELETE	/templates/{templateCode}

File upload

Files for mounting must be uploaded through the file upload API with source=sandbox_template.

Endpoint

POST https://{workspace_id}.{region}.maas.aliyuncs.com/api/v1/agentstudio/files

Multipart form upload

curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/files" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -F "file=@./config.json" \
  -F "source=sandbox_template"

Response:

{
  "id": "file_xxx",
  "type": "file",
  "filename": "config.json",
  "downloadable": false,
  "mime_type": "application/json",
  "size_bytes": 128,
  "status": "checking",
  "created_at": "2026-10-21T15:00:00+08:00",
  "request_id": "xxx"
}

Pre-signed URL upload

Use this option for large files or direct-to-OSS uploads.

1. Request an upload URL.

curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/files" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "config.json",
    "mimeType": "application/json",
    "sizeBytes": 128,
    "source": "sandbox_template"
  }'

2. PUT the file content to upload_url in the response. Do not set an additional Content-Type header; otherwise the request may fail with 403 SignatureDoesNotMatch.

3. Call POST /api/v1/agentstudio/files/{file_id}/complete to complete the upload.

4. Poll GET /api/v1/agentstudio/files/{file_id} until status becomes available.

Limits

Dimension	Limit
File size	50 MB
Total workspace file storage	100 GB
Retention	30 days

File types are validated by extension: .yaml is accepted; .csv, .yml, .sh, .whl, and .tar.gz are not supported; .ts returns a video-format error. The full supported range is determined by the service.

E2B Official Reference

Sandbox currently exposes an E2B-compatible HTTP API. Each endpoint's method, path, and response structure stay close to the official E2B definitions. Except for the Update Template endpoint, which is a Bailian-specific protocol, the common fields and semantics of the other endpoints can be found in the official E2B API documentation:

• E2B API Reference

SDK

In addition to calling the REST API directly, you can integrate via the official E2B SDK. See Manage and Use Instances.