Sandboxes

Create a sandbox

POST
/sandboxes

Authorization

ApiKeyAuth
AGENTBOX-API-KEY<token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://sandboxes" \  -H "Content-Type: application/json" \  -d '{    "poolName": "my-pool"  }'
{  "sandbox": {    "sandboxId": "5de15c92-8fb5-440f-a9ea-7f62f734f1b9",    "namespace": "t-team1-user1",    "poolName": "my-pool",    "podName": "my-pool-xy7k2",    "status": "Running",    "claimedAt": "2026-04-21T10:15:30Z",    "team": "team1",    "user": "user1"  }}
{  "error": "poolName is required"}
{  "error": "invalid API key"}
{  "error": "sandbox pool t-team1-user1/missing-pool not found",  "detail": {    "availablePools": [      {        "name": "my-pool",        "namespace": "t-team1-user1",        "idle": 2,        "running": 1,        "starting": 0      },      {        "name": "gpu-pool",        "namespace": "t-team1-user1",        "idle": 0,        "running": 0,        "starting": 1      }    ],    "hint": "Pool not found. Pick a name from availablePools, or call POST /v1/sandboxpools first."  }}
{  "error": "no idle pods available in pool my-pool",  "detail": {    "idle": 0,    "running": 3,    "starting": 0,    "stopping": 0,    "failed": 0,    "hint": "pool at capacity; wait for a running sandbox to be released or scale up"  }}
{  "error": "scale failed: QUOTA_EXCEEDED",  "detail": {    "errCode": "QUOTA_EXCEEDED",    "message": "user quota reached its hard cap",    "retryAfter": 30  }}
{  "error": "failed to generate sandbox UUID"}