Documentation

REST API Reference

Manage secure execution sandboxes, spin up remote workspaces, and run programmatic commands directly from your backend servers or custom AI agent scripts.

Authentication

All REST API requests require authentication. Pass your dashboard API key as a Bearer token in the `Authorization` header:

Request Headers

Authorization: Bearer YOUR_API_KEY

Testing Tip: For testing or integrations with Claude Desktop and command-line scripts, you can optionally append the key as a query parameter: `?token=YOUR_API_KEY` or `?key=YOUR_API_KEY`.

Create Sandbox Space

Allocates and starts a fresh, isolated Hugging Face sandbox VM container. Returns the unique `sandbox_id` and the websocket proxy gateway address.

POST /api/v1/sandbox/create

Example Request (cURL)

curl -X POST https://embedenv.com/api/v1/sandbox/create \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response (200 OK)

{
  "ok": true,
  "sandbox_id": "sbx-4f2a71e89b3d",
  "status": "building",
  "ws_url": "wss://spaces.huggingface.co/your-sandbox-socket-endpoint/ws",
  "message": "Sandbox workspace duplication initiated."
}

Execute Code / Command

Executes code snippets or shell command actions inside a specified active sandbox container environment.

POST /api/v1/sandbox/execute

JSON Payload Parameters

Parameter	Type	Required	Description
sandbox_id	string	Yes	The unique ID of the target container space returned by the create API.
code	string	Yes	The Python code snippet or shell script payload to execute.
language	string	No	Must be `python` (default) or `bash`. If python, it compiles the text as a script file and runs it. If bash, it runs the raw shell commands directly.

Example Python Request (cURL)

curl -X POST https://embedenv.com/api/v1/sandbox/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sandbox_id": "sbx-4f2a71e89b3d",
    "code": "print(123 + 456)",
    "language": "python"
  }'

Example Response (200 OK)

{
  "ok": true,
  "stdout": "579\n",
  "stderr": "",
  "credits_remaining": 9480
}