Sandbox lifecycle API

The API uses sessionId as the identifier for a customer-visible sandbox. Lifecycle requests use a workspace bearer key and the https://api.archal.ai origin.

List environments

GET /api/environments
Authorization: Bearer archal_ws_...

Use this response instead of hard-coding availability, capabilities, state contracts, or certification admission.

Create

POST /api/sessions
Authorization: Bearer archal_ws_...
Idempotency-Key: ci-run-123
Content-Type: application/json

{
  "environments": ["github", "supabase"],
  "ttlSeconds": 1800,
  "initialState": {
    "github": {
      "format": "json",
      "value": { "users": [], "repos": [], "issues": [] }
    },
    "supabase": {
      "format": "sql",
      "value": "create table public.todos (id bigint primary key);"
    }
  }
}

Idempotency-Key is required and must be 200 characters or fewer. A successful create returns 201. The sandbox may still be starting, with null connections until readiness.

Inspect and wait

GET /api/sessions/{sessionId}
Authorization: Bearer archal_ws_...

Poll with bounded backoff until every selected environment has status: ready and the sandbox reports alive: true. Stop on failed, ended, or expired. Ready connections contain apiBaseUrl, optional mcpUrl, and scoped credentials.headers. Do not call the data plane with the workspace key.

List

GET /api/sessions
Authorization: Bearer archal_ws_...

The list is workspace-scoped and capped by server policy.

Renew

POST /api/sessions/{sessionId}/renew
Authorization: Bearer archal_ws_...
Content-Type: application/json

{
  "ttlSeconds": 1800
}

Read the returned expiry, lease, and refreshed connections. Renewal can rotate provider credentials.

Reset

POST /api/sessions/{sessionId}/reset
Authorization: Bearer archal_ws_...

Reset one environment through its more specific endpoint:

POST /api/sessions/{sessionId}/environments/{environmentId}/reset
Authorization: Bearer archal_ws_...

Destroy

Wait for physical teardown and return 204:

DELETE /api/sessions/{sessionId}
Authorization: Bearer archal_ws_...

Or request fast durable acceptance and return 202:

DELETE /api/sessions/{sessionId}
Authorization: Bearer archal_ws_...
Prefer: respond-async

Asynchronous acceptance stops billing after teardown intent is durable. Physical deletion continues separately and can be checked through the status endpoint.

Guides

OpenAPI

Sandbox lifecycle API

List environments

Create

Inspect and wait

List

Renew

Reset

Destroy

​List environments

​Create

​Inspect and wait

​List

​Renew

​Reset

​Destroy

List environments

Create

Inspect and wait

List

Renew

Reset

Destroy