> ## 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}
{
  "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.
Send the state object itself to this REST endpoint. The `{ format, value }`
wrapper is used by the SDK and by `initialState` during session creation; the
SDK removes that wrapper when it calls this endpoint.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.