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.

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/reconnect'

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