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.
POST /api/environments/{environmentId}/state/validateAuthorization: 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.
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.
PUT /api/sessions/{sessionId}/environments/{environmentId}/stateAuthorization: Bearer archal_ws_...Content-Type: application/json
Supabase SQL:
PUT /api/sessions/{sessionId}/environments/supabase/stateAuthorization: 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.
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.
Was this page helpful?
{"docsConfig":{"theme":"aspen","$schema":"https://mintlify.com/docs.json","name":"Archal","description":"Create testing sandboxes with isolated, stateful provider environments.","colors":{"primary":"#A8887A","light":"#C1A89C","dark":"#7A6C5A"},"logo":{"light":"https://mintcdn.com/archallabs/IGeHrsqAwIcGu23r/logo/archal-mark.png?fit=max\u0026auto=format\u0026n=IGeHrsqAwIcGu23r\u0026q=85\u0026s=8078899310b6e3d2efa751734115c6e7","dark":"https://mintcdn.com/archallabs/IGeHrsqAwIcGu23r/logo/archal-mark.png?fit=max\u0026auto=format\u0026n=IGeHrsqAwIcGu23r\u0026q=85\u0026s=8078899310b6e3d2efa751734115c6e7","href":"https://archal.ai"},"favicon":"https://mintcdn.com/archallabs/IGeHrsqAwIcGu23r/favicon.png?fit=max\u0026auto=format\u0026n=IGeHrsqAwIcGu23r\u0026q=85\u0026s=1e9f095639a2789438f18526d6c1c8a4","appearance":{"default":"dark"},"background":{"color":{"light":"#F7F3EC","dark":"#0A0806"}},"navbar":{"links":[{"href":"https://archal.ai/dashboard","label":"Dashboard"}]},"footer":{"socials":{"github":"https://github.com/Archal-Labs/archal","website":"https://archal.ai"},"links":[{"header":"Archal","items":[{"label":"Home","href":"https://archal.ai"},{"label":"Dashboard","href":"https://archal.ai/dashboard"}]},{"header":"Docs","items":[{"label":"Start","href":"https://docs.archal.ai/introduction"},{"label":"Sandboxes","href":"https://docs.archal.ai/sandboxes/overview"},{"label":"Environments","href":"https://docs.archal.ai/environments/overview"},{"label":"API reference","href":"https://docs.archal.ai/api-reference/openapi.json"}]},{"header":"Company","items":[{"label":"Contact","href":"https://archal.ai/contact"},{"label":"GitHub","href":"https://github.com/Archal-Labs/archal"}]}]},"seo":{"metatags":{"og:site_name":"Archal Docs","og:image":"https://docs.archal.ai/images/og-default.png","twitter:card":"summary_large_image","twitter:image":"https://docs.archal.ai/images/og-default.png"},"indexing":"navigable"},"fonts":{"heading":{"family":"Inter","weight":600,"source":"google","format":"woff2"},"body":{"family":"Inter","source":"google","format":"woff2"}},"contextual":{"options":["copy","view","chatgpt","claude"],"display":"header"},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"archallabs","hasAudioNarration":false,"actualSubdomain":"archallabs","customDomains":["docs.archal.ai"],"gitSource":{"type":"github","owner":"archal-labs","repo":"archal","deployBranch":"main","contentDirectory":"apps/web/docs","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6a928e5b08b3839763e4be45","collectionId":"764508c1-61dd-4410-94b4-7f0893b71e48","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6a928e5b08b3839763e4be45"},"feedback":{"thumbs":true,"agentFeedback":true},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6a928e5b08b3839763e4be45","clientVersion":"0.0.4054","searchFilterCounts":[{"language":"default","tag":"API Reference","count":51},{"language":"default","tag":"Environments","count":46},{"language":"default","tag":"OpenAPI","count":21},{"language":"default","tag":"Sandboxes","count":12},{"language":"default","tag":"Start","count":10},{"language":"default","tag":"Integrate","count":10},{"language":"default","tag":"Guides","count":9}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api/starting-state","slug":"/api/starting-state","pageMetadata":{"title":"State API","description":"Validate, load, inspect, and compare explicit environment state.","href":"/api/starting-state"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Validate, load, inspect, and compare explicit environment state.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={code:`code`,p:`p`,pre:`pre`,span:`span`,..._provideComponents(),...props.components},{CodeBlock,Heading,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`All 22 current environments publish a versioned state contract and accept JSON.\nSupabase also accepts guarded SQL, and its five canonical samples are SQL.`}),`\n`,_jsx(Heading,{level:`2`,id:`validate-without-starting-a-sandbox`,children:`Validate without starting a sandbox`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`http`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`http`,children:_jsxs(_components.code,{language:`http`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`POST`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` /api/environments/{environmentId}/state/validate`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#569CD6`},children:`Authorization`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` Bearer archal_ws_...`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#569CD6`},children:`Content-Type`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` application/json`})]}),`\n`]})})}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`5`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`5`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"users\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [],`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"repos\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [],`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"issues\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: []`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The response reports whether the payload matches the current environment\ncontract. Validation does not start usage or claim hosted behavior was verified.\nSend the state object itself to this REST endpoint. The `,_jsx(_components.code,{children:`{ format, value }`}),`\nwrapper is used by the SDK and by `,_jsx(_components.code,{children:`initialState`}),` during session creation; the\nSDK removes that wrapper when it calls this endpoint.`]}),`\n`,_jsx(Heading,{level:`2`,id:`load-during-creation`,children:`Load during creation`}),`\n`,_jsxs(_components.p,{children:[`Send `,_jsx(_components.code,{children:`initialState`}),` in `,_jsx(_components.code,{children:`POST /api/sessions`}),`. The sandbox becomes ready only\nafter every environment accepts its input. If one load fails, Archal cleans up\nthe whole new sandbox.`]}),`\n`,_jsx(Heading,{level:`2`,id:`read-current-state`,children:`Read current state`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`http`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`http`,children:_jsxs(_components.code,{language:`http`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`GET`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` /api/sessions/{sessionId}/environments/{environmentId}/state`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#569CD6`},children:`Authorization`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` Bearer archal_ws_...`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`The response includes the current state and its environment identity.`}),`\n`,_jsx(Heading,{level:`2`,id:`replace-state`,children:`Replace state`}),`\n`,_jsx(_components.p,{children:`JSON:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`http`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`http`,children:_jsxs(_components.code,{language:`http`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`PUT`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` /api/sessions/{sessionId}/environments/{environmentId}/state`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#569CD6`},children:`Authorization`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` Bearer archal_ws_...`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#569CD6`},children:`Content-Type`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` application/json`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`Supabase SQL:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`http`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`http`,children:_jsxs(_components.code,{language:`http`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`PUT`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` /api/sessions/{sessionId}/environments/supabase/state`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#569CD6`},children:`Authorization`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` Bearer archal_ws_...`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#569CD6`},children:`Content-Type`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` text/sql`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`State replacement overwrites current data. JSON environments treat a\nsuccessful load as the new reset baseline. The canonical Supabase samples\ncurrently encode an expectation that reset restores the original session seed,\nso verify that behavior before relying on a later SQL load as its baseline.`}),`\n`,_jsx(Heading,{level:`2`,id:`diff-against-an-explicit-snapshot`,children:`Diff against an explicit snapshot`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`http`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`http`,children:_jsxs(_components.code,{language:`http`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`POST`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` /api/sessions/{sessionId}/environments/{environmentId}/state/diff`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#569CD6`},children:`Authorization`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` Bearer archal_ws_...`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#569CD6`},children:`Content-Type`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` application/json`})]}),`\n`]})})}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`9`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`9`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"source\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"explicit\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"before\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"users\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [],`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"repos\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [],`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"issues\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: []`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"maxChanges\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`100`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`The server returns before and after hashes, changed paths, counts, and\ntruncation metadata. It does not infer a hidden before state.`}),`\n`,_jsx(Heading,{level:`2`,id:`sql-safety-boundary`,children:`SQL safety boundary`}),`\n`,_jsxs(_components.p,{children:[`Supabase SQL is for schema and synthetic fixtures. Archal rejects cluster and\ndatabase management, external data access, `,_jsx(_components.code,{children:`COPY`}),`, role or session\nauthorization changes, server-library loading, transaction control, and psql\nmeta-commands before the payload reaches the environment.`]}),`\n`,_jsx(Warning,{children:_jsx(_components.p,{children:`State replacement is destructive. Use synthetic data, capture current state when it matters, and\nnever upload production secrets or a raw production database snapshot.`})})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"State API","description":"Validate, load, inspect, and compare explicit environment state.","href":"/api/starting-state"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Validate without starting a sandbox","slug":"validate-without-starting-a-sandbox","depth":2,"children":[]},{"title":"Load during creation","slug":"load-during-creation","depth":2,"children":[]},{"title":"Read current state","slug":"read-current-state","depth":2,"children":[]},{"title":"Replace state","slug":"replace-state","depth":2,"children":[]},{"title":"Diff against an explicit snapshot","slug":"diff-against-an-explicit-snapshot","depth":2,"children":[]},{"title":"SQL safety boundary","slug":"sql-safety-boundary","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"archallabs","siteName":"Archal","title":"State API - Archal","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-08-09T08:32:54.521Z","originalFileLocation":"api/starting-state.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"dark\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Validate, load, inspect, and compare explicit environment state.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Archal\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/archallabs/sxRzDHx4Ey09YHTe/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/archallabs/sxRzDHx4Ey09YHTe/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/archallabs/sxRzDHx4Ey09YHTe/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/archallabs/sxRzDHx4Ey09YHTe/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/archallabs/sxRzDHx4Ey09YHTe/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/archallabs/sxRzDHx4Ey09YHTe/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/archallabs/sxRzDHx4Ey09YHTe/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/archallabs/sxRzDHx4Ey09YHTe/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/archallabs/sxRzDHx4Ey09YHTe/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"State API - Archal\">\u003cmeta data-mint-head property=\"og:description\" content=\"Validate, load, inspect, and compare explicit environment state.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Archal Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.archal.ai/api/starting-state\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://docs.archal.ai/images/og-default.png\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"State API - Archal\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Validate, load, inspect, and compare explicit environment state.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://docs.archal.ai/images/og-default.png\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/archallabs/sxRzDHx4Ey09YHTe/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Archal\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#A8887A\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.archal.ai/api/starting-state\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api/starting-state.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.archal.ai/#organization\",\"name\":\"Archal\",\"url\":\"https://docs.archal.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/archallabs/IGeHrsqAwIcGu23r/logo/archal-mark.png?fit=max\u0026auto=format\u0026n=IGeHrsqAwIcGu23r\u0026q=85\u0026s=8078899310b6e3d2efa751734115c6e7\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.archal.ai#website\",\"name\":\"Archal\",\"url\":\"https://docs.archal.ai\",\"publisher\":{\"@id\":\"https://docs.archal.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.archal.ai/api/starting-state#webpage\",\"url\":\"https://docs.archal.ai/api/starting-state\",\"name\":\"State API\",\"description\":\"Validate, load, inspect, and compare explicit environment state.\",\"dateModified\":\"2026-08-09T08:32:54.521Z\",\"isPartOf\":{\"@id\":\"https://docs.archal.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.archal.ai/api/starting-state#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.archal.ai/api/starting-state#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Guides\",\"item\":\"https://docs.archal.ai/api/authentication\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"State API\",\"item\":\"https://docs.archal.ai/api/starting-state\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.archal.ai/api/starting-state#article\",\"headline\":\"State API\",\"name\":\"State API\",\"description\":\"Validate, load, inspect, and compare explicit environment state.\",\"url\":\"https://docs.archal.ai/api/starting-state\",\"mainEntityOfPage\":{\"@id\":\"https://docs.archal.ai/api/starting-state#webpage\"},\"image\":\"https://docs.archal.ai/images/og-default.png\",\"dateModified\":\"2026-08-09T08:32:54.521Z\",\"publisher\":{\"@id\":\"https://docs.archal.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.archal.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Archal\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Archal","nav":{"global":null,"tabs":[{"tab":"Start","pages":[{"title":"Start","href":"/introduction"}]},{"tab":"Sandboxes","pages":[{"title":"Sandboxes","href":"/sandboxes/overview"}]},{"tab":"Environments","pages":[{"title":"Environments","href":"/environments/overview"}]},{"tab":"Integrate","pages":[{"title":"Integrate","href":"/integrations/coding-agents"}]},{"tab":"API Reference","groups":[{"group":"Guides","pages":[{"title":"Authentication","href":"/api/authentication"},{"title":"Sandbox lifecycle API","description":"Create, inspect, renew, reset, and destroy sandboxes through the current REST contract.","href":"/api/lifecycle"},{"title":"State API","href":"/api/starting-state"},{"title":"Call an environment","description":"Send provider-shaped requests with the session-scoped credentials returned at readiness.","href":"/api/call-environment"},{"title":"Reset API","href":"/api/reset-state"},{"title":"Errors and retries","href":"/api/errors-retries"},{"title":"Idempotency","href":"/api/idempotency"},{"title":"Limits and usage","href":"/api/limits-usage"},{"title":"Data handling and security","href":"/security"}]},{"group":"OpenAPI","pages":[{"group":"API Reference","pages":[{"title":"List environment capabilities and state contracts","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/environments","href":"/api-reference/list-environment-capabilities-and-state-contracts"},{"title":"Describe one environment and its certification","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/environments/{environmentId}","href":"/api-reference/describe-one-environment-and-its-certification"},{"title":"Validate state without starting an environment","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/environments/{environmentId}/state/validate","href":"/api-reference/validate-state-without-starting-an-environment"},{"title":"List environment sessions","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/sessions","href":"/api-reference/list-environment-sessions"},{"title":"Create environments with optional initial state","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/sessions","href":"/api-reference/create-environments-with-optional-initial-state"},{"title":"Inspect readiness and environment connection URLs","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/sessions/{sessionId}","href":"/api-reference/inspect-readiness-and-environment-connection-urls"},{"title":"Destroy a session and release its runtime resources","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /api/sessions/{sessionId}","href":"/api-reference/destroy-a-session-and-release-its-runtime-resources"},{"title":"Extend an active environment session","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/sessions/{sessionId}/renew","href":"/api-reference/extend-an-active-environment-session"},{"title":"Reset every stateful environment in a session","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/sessions/{sessionId}/reset","href":"/api-reference/reset-every-stateful-environment-in-a-session"},{"title":"Inspect environment state","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/sessions/{sessionId}/environments/{environmentId}/state","href":"/api-reference/inspect-environment-state"},{"title":"Replace environment state and its reset baseline","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /api/sessions/{sessionId}/environments/{environmentId}/state","href":"/api-reference/replace-environment-state-and-its-reset-baseline"},{"title":"Reset one environment to its baseline","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/sessions/{sessionId}/environments/{environmentId}/reset","href":"/api-reference/reset-one-environment-to-its-baseline"},{"title":"Compare explicit prior state with current state","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/sessions/{sessionId}/environments/{environmentId}/state/diff","href":"/api-reference/compare-explicit-prior-state-with-current-state"},{"title":"Get bounded request metadata and retention status","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/sessions/{sessionId}/evidence","href":"/api-reference/get-bounded-request-metadata-and-retention-status"},{"title":"Send a GET request to an environment","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/sessions/{sessionId}/environments/{environmentId}/api/{providerPath}","href":"/api-reference/send-a-get-request-to-an-environment"},{"title":"Send a PUT request to an environment","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/sessions/{sessionId}/environments/{environmentId}/api/{providerPath}","href":"/api-reference/send-a-put-request-to-an-environment"},{"title":"Send a POST request to an environment","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/sessions/{sessionId}/environments/{environmentId}/api/{providerPath}","href":"/api-reference/send-a-post-request-to-an-environment"},{"title":"Send a DELETE request to an environment","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/sessions/{sessionId}/environments/{environmentId}/api/{providerPath}","href":"/api-reference/send-a-delete-request-to-an-environment"},{"title":"Send a HEAD request to an environment","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json head /v1/sessions/{sessionId}/environments/{environmentId}/api/{providerPath}","href":"/api-reference/send-a-head-request-to-an-environment"},{"title":"Send a PATCH request to an environment","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/sessions/{sessionId}/environments/{environmentId}/api/{providerPath}","href":"/api-reference/send-a-patch-request-to-an-environment"},{"title":"Send a Streamable HTTP MCP request to an environment","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/sessions/{sessionId}/environments/{environmentId}/mcp","href":"/api-reference/send-a-streamable-http-mcp-request-to-an-environment"}]}]}]}]},"basePath":"","title":"State API - Archal","buildId":"dpl_345ReqzYaAjzS9QpeJemsKdb7KDj","deploymentId":"dpl_345ReqzYaAjzS9QpeJemsKdb7KDj","dynamics":[],"chunks":[]}
