API REFERENCE

Reconnect to session sandbox

On this page

GET/api/sandbox/reconnect

Live runtime probe for the sandbox bound to a session. Unlike GET /api/sandbox/status (DB-only read), this endpoint actually runs a quick command inside the sandbox to verify it is reachable. Used by the chat UI on session re-entry / tab refocus to decide whether to flip out of "loading sandbox…" or surface a "resume" affordance. Returns one of three operational outcomes via the status field: "connected" (sandbox is alive, included expiresAt reflects current expiry), "expired" (the runtime state is gone — the UI should offer to resume from snapshot if hasSnapshot is true, otherwise create a fresh sandbox), or "no_sandbox" (no sandbox has been provisioned for this session yet).

Authentication

x-api-key in header

BearerAuth bearer

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/sandbox/reconnect?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.

Parameters

Query parameters

sessionIdstringrequired

The id of the session whose sandbox to reconnect to.

Responses

200Reconnect probe completed. Inspect status for the outcome.

application/json

statusstring · enumrequired

connected when the live runtime probe succeeded; expired when the recorded runtime state is no longer reachable (the UI should offer resume-from-snapshot or fresh-create); no_sandbox when the session has never had a sandbox provisioned.

Values: "connected", "expired", "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 on expired / no_sandbox.

expiresAtinteger

Epoch milliseconds when the sandbox runtime will expire. Present only when status is "connected"; reflects the freshly-probed expiry, which may differ from lifecycle.sandboxExpiresAt if the sandbox extended itself between writes.

format: int64

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": "Reconnect to session sandbox",
  "description": "Live runtime probe for the sandbox bound to a session. Unlike `GET /api/sandbox/status` (DB-only read), this endpoint actually runs a quick command inside the sandbox to verify it is reachable. Used by the chat UI on session re-entry / tab refocus to decide whether to flip out of \"loading sandbox…\" or surface a \"resume\" affordance. Returns one of three operational outcomes via the `status` field: `\"connected\"` (sandbox is alive, included `expiresAt` reflects current expiry), `\"expired\"` (the runtime state is gone — the UI should offer to resume from snapshot if `hasSnapshot` is true, otherwise create a fresh sandbox), or `\"no_sandbox\"` (no sandbox has been provisioned for this session yet).",
  "parameters": [
    {
      "name": "sessionId",
      "in": "query",
      "required": true,
      "description": "The id of the session whose sandbox to reconnect to.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Reconnect probe completed. Inspect `status` for the outcome.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReconnectResponse"
          }
        }
      }
    },
    "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"
          }
        }
      }
    }
  }
}