> ## 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.

# State API

> Validate, load, inspect, and compare explicit environment state.

All 22 current environments publish a versioned state contract and accept JSON.
Supabase also accepts guarded SQL, and its five canonical samples are SQL.

## Validate without starting a sandbox

```http theme={null}
POST /api/environments/{environmentId}/state/validate
Authorization: Bearer archal_ws_...
Content-Type: application/json
```

```json theme={null}
{
  "format": "json",
  "value": {
    "users": [],
    "repos": [],
    "issues": []
  }
}
```

The response reports whether the payload matches the current environment
contract. Validation does not start usage or claim hosted behavior was verified.

## Load during creation

Send `initialState` in `POST /api/sessions`. The sandbox becomes ready only
after every environment accepts its input. If one load fails, Archal cleans up
the whole new sandbox.

## Read current state

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

The response includes the current state and its environment identity.

## Replace state

JSON:

```http theme={null}
PUT /api/sessions/{sessionId}/environments/{environmentId}/state
Authorization: Bearer archal_ws_...
Content-Type: application/json
```

Supabase SQL:

```http theme={null}
PUT /api/sessions/{sessionId}/environments/supabase/state
Authorization: Bearer archal_ws_...
Content-Type: text/sql
```

State replacement overwrites current data. JSON environments treat a
successful load as the new reset baseline. The canonical Supabase samples
currently encode an expectation that reset restores the original session seed,
so verify that behavior before relying on a later SQL load as its baseline.

## Diff against an explicit snapshot

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

```json theme={null}
{
  "source": "explicit",
  "before": {
    "users": [],
    "repos": [],
    "issues": []
  },
  "maxChanges": 100
}
```

The server returns before and after hashes, changed paths, counts, and
truncation metadata. It does not infer a hidden before state.

## SQL safety boundary

Supabase SQL is for schema and synthetic fixtures. Archal rejects cluster and
database management, external data access, `COPY`, role or session
authorization changes, server-library loading, transaction control, and psql
meta-commands before the payload reaches the environment.

<Warning>
  State replacement is destructive. Use synthetic data, capture current state when it matters, and
  never upload production secrets or a raw production database snapshot.
</Warning>