> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox lifecycle API

> Create, inspect, renew, reset, and destroy sandboxes through the current REST contract.

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

```http theme={null}
GET /api/environments
Authorization: Bearer archal_ws_...
```

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

## Create

```http theme={null}
POST /api/sessions
Authorization: Bearer archal_ws_...
Idempotency-Key: ci-run-123
Content-Type: application/json
```

```json theme={null}
{
  "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

```http theme={null}
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

```http theme={null}
GET /api/sessions
Authorization: Bearer archal_ws_...
```

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

## Renew

```http theme={null}
POST /api/sessions/{sessionId}/renew
Authorization: Bearer archal_ws_...
Content-Type: application/json
```

```json theme={null}
{
  "ttlSeconds": 1800
}
```

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

## Reset

```http theme={null}
POST /api/sessions/{sessionId}/reset
Authorization: Bearer archal_ws_...
```

Reset one environment through its more specific endpoint:

```http theme={null}
POST /api/sessions/{sessionId}/environments/{environmentId}/reset
Authorization: Bearer archal_ws_...
```

## Destroy

Wait for physical teardown and return `204`:

```http theme={null}
DELETE /api/sessions/{sessionId}
Authorization: Bearer archal_ws_...
```

Or request fast durable acceptance and return `202`:

```http theme={null}
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.