Skip to main content

Overview

Service address, protocol conventions, and endpoint list of the Sandbox API, which is E2B-compatible and forwarded through the Bailian AI gateway.

Before calling, configure Authentication. For error handling, see Error Codes.
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

CapabilityMethodPath
Create instancePOST/sandboxes
List instancesGET/v2/sandboxes
Get instanceGET/sandboxes/{sandboxID}
Connect to instancePOST/sandboxes/{sandboxID}/connect
Pause instancePOST/sandboxes/{sandboxID}/pause
Resume instancePOST/sandboxes/{sandboxID}/resume
Release instanceDELETE/sandboxes/{sandboxID}

Template Management

CapabilityMethodPath
Create templatePOST/v3/templates
List templatesGET/v2/templates
Get templateGET/templates/{templateCode}
Update templatePUT/templates/{templateCode}
Get build statusGET/templates/{templateCode}/builds/{buildID}/status
Delete templateDELETE/templates/{templateCode}
To create or update a template, upload the file for mntConfig as described in File upload, and pass source=sandbox_template, then wait for status to become available.

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"
  }'
  1. 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.
  2. Call POST /api/v1/agentstudio/files/{file_id}/complete to complete the upload.
  3. Poll GET /api/v1/agentstudio/files/{file_id} until status becomes available.

Limits

DimensionLimit
File size50 MB
Total workspace file storage100 GB
Retention30 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.
Only files with source=sandbox_template and status=available can be added to mntConfig. For file error codes, see Errors.

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:
This documentation lists only the endpoints and Bailian extension fields that Bailian supports. Bailian's authentication, endpoint, and extension configurations follow this documentation; common protocol fields can be cross-referenced with the official E2B docs.

SDK

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