Sandboxes
Overview
Sandboxes are Tenant-owned durable Agent execution environments with optional Attribution. Use these endpoints to allocate and configure one before Agent attachment, inspect it, or delete it after detachment; foreign IDs return not found.
Endpoints
POST /v1/sandboxes
Creates a durable Sandbox. Sandboxes are Tenant-owned and optionally attributed; IDs outside the Tenant return not found.
Request
Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.
| Location | Field | Required | Description |
|---|---|---|---|
| Header | Authorization | yes | Tenant API key or dashboard Supabase JWT. |
| Location | Field | Required | Description |
|---|---|---|---|
| Body | name | no | Display name; omitted generates sandbox--<8 ID characters>. |
| Body | userId | no | Immutable Attribution; defaults to "". |
| Body | metadata | no | Attribution metadata; defaults to {}. |
| Header | Content-Type | yes | application/json. |
Response
| Status | Body | Lifecycle effect |
|---|---|---|
201 Created | Sandbox | Allocates the durable resource record with deny-by-default network policy. |
Response schema: sandboxSchema.
Errors
400 invalid_request and service availability errors. See REST errors.
cURL
curl --request POST "$BLAZING_AGENTS_BASE_URL/v1/sandboxes" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"Coding","userId":"user-42"}'SDK and related guides
SDK: create. See Sandboxes and Build a coding Agent.
GET /v1/sandboxes
Lists Sandboxes. Sandboxes are Tenant-owned and optionally attributed; IDs outside the Tenant return not found.
Request
Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.
| Location | Field | Required | Description |
|---|---|---|---|
| Header | Authorization | yes | Tenant API key or dashboard Supabase JWT. |
| Location | Field | Required | Description |
|---|---|---|---|
| Query | cursor | no | Opaque cursor. |
| Query | limit | no | 1–200; defaults to 50. |
| Query | userId | no | Exact Attribution filter. |
Response
| Status | Body | Lifecycle effect |
|---|---|---|
200 OK | SandboxesListResponse | Read-only. |
Use nextCursor until it is null.
Response schema: sandboxesListResponseSchema.
Errors
400 invalid_request. See REST errors.
cURL
curl --get "$BLAZING_AGENTS_BASE_URL/v1/sandboxes" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
--data-urlencode "userId=user-42"SDK and related guides
SDK: list. See Sandboxes and Build a coding Agent.
GET /v1/sandboxes/:sandboxId
Gets one Sandbox. Sandboxes are Tenant-owned and optionally attributed; IDs outside the Tenant return not found.
Request
Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.
| Location | Field | Required | Description |
|---|---|---|---|
| Header | Authorization | yes | Tenant API key or dashboard Supabase JWT. |
| Path | sandboxId | yes | Sandbox ID (sb_…). |
Response
| Status | Body | Lifecycle effect |
|---|---|---|
200 OK | Sandbox | Read-only. |
Response schema: sandboxSchema.
Errors
404 SANDBOX_NOT_FOUND. See REST errors.
cURL
curl "$BLAZING_AGENTS_BASE_URL/v1/sandboxes/sb_1234567890ABCDEF" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"SDK and related guides
SDK: get. See Sandboxes and Build a coding Agent.
PUT /v1/sandboxes/:sandboxId
Updates mutable Sandbox fields. Sandboxes are Tenant-owned and optionally attributed; IDs outside the Tenant return not found.
Request
Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.
| Location | Field | Required | Description |
|---|---|---|---|
| Header | Authorization | yes | Tenant API key or dashboard Supabase JWT. |
| Path | sandboxId | yes | Sandbox ID (sb_…). |
| Location | Field | Required | Description |
|---|---|---|---|
| Body | name | alternative | New display name. |
| Body | metadata | alternative | Replacement metadata; at least one field is required. |
| Header | Content-Type | yes | application/json. |
Response
| Status | Body | Lifecycle effect |
|---|---|---|
200 OK | Sandbox | Updates configuration without changing Attribution or network policy. |
Response schema: sandboxSchema.
Errors
400 invalid_request; 404 SANDBOX_NOT_FOUND; 409 SANDBOX_DELETE_CONFLICT. See REST errors.
cURL
curl --request PUT "$BLAZING_AGENTS_BASE_URL/v1/sandboxes/sb_1234567890ABCDEF" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"Coding production"}'SDK and related guides
SDK: update. See Sandboxes and Build a coding Agent.
DELETE /v1/sandboxes/:sandboxId
Starts or completes Sandbox deletion. Sandboxes are Tenant-owned and optionally attributed; IDs outside the Tenant return not found.
Request
Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.
| Location | Field | Required | Description |
|---|---|---|---|
| Header | Authorization | yes | Tenant API key or dashboard Supabase JWT. |
| Path | sandboxId | yes | Sandbox ID (sb_…). |
Response
| Status | Body | Lifecycle effect |
|---|---|---|
204 No Content or 202 Accepted | Empty when complete; { "status": "deleting" } when pending | Deletes immediately or marks asynchronous deletion pending. |
Pending response schema: sandboxDeletionPendingResponseSchema.
On 202, poll GET until the Sandbox is no longer returned. Repeating delete follows the service's deletion state.
Errors
404 SANDBOX_NOT_FOUND; 409 SANDBOX_IN_USE or SANDBOX_DELETE_CONFLICT. See REST errors.
cURL
curl --request DELETE "$BLAZING_AGENTS_BASE_URL/v1/sandboxes/sb_1234567890ABCDEF" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"SDK and related guides
SDK: delete. See Sandboxes and Build a coding Agent.