API REFERENCE

Get session sandbox status

On this page

GET/api/sandbox/status

Returns the current lifecycle and runtime state for the sandbox bound to a session. The chat UI polls this endpoint while showing the "loading sandbox…" state and flips to "ready" when status becomes active. The response includes lifecycleVersion (an optimistic concurrency token) and a lifecycle envelope with serverTime, the lifecycle FSM state, and timestamps for last activity, hibernation deadline, and sandbox expiry. As a side effect, if the runtime state is stale (expired or overdue for hibernation), the lifecycle workflow is kicked to clean up — callers do not need to do this themselves.

Authentication

x-api-key in header

BearerAuth bearer

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/sandbox/status?sessionId=YOUR_SESSIONID' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

sessionIdquery · stringrequired

cURL for this request

curl --request GET \
  --url 'https://recoup-api.vercel.app/api/sandbox/status'

Parameters

Query parameters

sessionIdstringrequired

The id of the session whose sandbox status to read.

Responses

200Sandbox status retrieved successfully.

application/json

statusstring · enumrequired

active when a non-expired sandbox is bound to the session; no_sandbox otherwise. The chat UI flips out of its loading state when this becomes active.

Values: "active", "no_sandbox"

hasSnapshotbooleanrequired

True when a paused/snapshotted sandbox exists and can be resumed. Used by the UI to decide whether to show "resume" vs "create" affordances when status is no_sandbox.

lifecycleVersionintegerrequired

Optimistic concurrency token for lifecycle transitions. Clients can pass this back to lifecycle-mutating endpoints to detect races.

lifecycleobjectrequired

Lifecycle envelope shared between GET /api/sandbox/status and GET /api/sandbox/reconnect. Server-clock-stamped snapshot of the sandbox's lifecycle FSM state and the timestamps the UI uses to render countdown timers.

Properties

serverTimeintegerrequired

Server's current epoch milliseconds. Use this — not the client clock — when computing how much time is left before hibernateAfter or sandboxExpiresAt.

format: int64

statestring · enumrequirednullable

Lifecycle FSM state. null for sessions that have never had a sandbox.

Values: "provisioning", "active", "hibernating", "hibernated", "restoring", "archived", "failed"

lastActivityAtintegerrequirednullable

Epoch milliseconds of the last recorded sandbox activity, or null if there has been none.

format: int64

hibernateAfterintegerrequirednullable

Epoch milliseconds after which the sandbox is eligible for hibernation, or null when not applicable.

format: int64

sandboxExpiresAtintegerrequirednullable

Epoch milliseconds when the sandbox runtime expires, or null when not applicable.

format: int64

400Missing sessionId query parameter.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

401Unauthorized — invalid or missing API key / Bearer token.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

403Forbidden — the authenticated account does not own this session.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

404Not found — no session exists with the given sessionId.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download sandbox.json

View operation source

json

{
  "summary": "Get session sandbox status",
  "description": "Returns the current lifecycle and runtime state for the sandbox bound to a session. The chat UI polls this endpoint while showing the \"loading sandbox…\" state and flips to \"ready\" when `status` becomes `active`. The response includes `lifecycleVersion` (an optimistic concurrency token) and a `lifecycle` envelope with `serverTime`, the lifecycle FSM `state`, and timestamps for last activity, hibernation deadline, and sandbox expiry. As a side effect, if the runtime state is stale (expired or overdue for hibernation), the lifecycle workflow is kicked to clean up — callers do not need to do this themselves.",
  "parameters": [
    {
      "name": "sessionId",
      "in": "query",
      "required": true,
      "description": "The id of the session whose sandbox status to read.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Sandbox status retrieved successfully.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SandboxStatusResponse"
          }
        }
      }
    },
    "400": {
      "description": "Missing `sessionId` query parameter.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized — invalid or missing API key / Bearer token.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden — the authenticated account does not own this session.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Not found — no session exists with the given `sessionId`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}