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

POST /api/environments/{environmentId}/state/validate
Authorization: Bearer archal_ws_...
Content-Type: application/json

{
  "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

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

The response includes the current state and its environment identity.

​

Replace state

JSON:

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

Supabase SQL:

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

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

{
  "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.

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