Rensei docs
API ReferenceInteractive sessions

Get one interactive session's detail.

Authentication accepts a browser session or a WorkOS user token only; an rsk API key or a BYOA OAuth-agent token is rejected 403 (no user identity to derive driver/viewer capability from). Returns 404 - never 403 - for a session belonging to a different org or one the caller has no project access/grant for, so existence is never leaked across the boundary.

GET
/api/interactive-sessions/{id}

Authorization

headerAuthorizationBearer <rsk_live_*>

Rensei API key presented as Authorization: Bearer rsk_live_. Required API-key scopes are recorded per operation in x-rensei-required-scopes.

Path Parameters

id*string

The session id (agent_sessions.session_id).

Response Body

Session detail.

application/json
  1. response
id*string
sessionId*string
orgId*string
projectId*string
createdByUserId*string|null
status*string
Value in"provisioning""active""paused""ended""failed"
liveStatus*string|null
hostAlive*|

Null when not applicable (status is not paused/unknown); otherwise whether session-restart-fence still carries a live adopted shim lineage for this session — the platform truth this GET auto-rebinds on when true. A GET that finds this true has already rebound the session (see status above), so a client will see this true only in the narrow race where the rebind itself lost a concurrent write.

poolId*string|null
poolName*|

Human-readable workarea/pool name resolved server-side; falls back to poolId only when the referent is gone.

harness*string|null
harnessName*|

Human-readable harness name resolved server-side; falls back to harness only when the referent is gone.

modelProfileId*string|null
modelName*|

Human-readable model profile name resolved server-side; falls back to modelProfileId only when the referent is gone.

modelSlug*|

Human-readable model profile slug resolved server-side, retained alongside modelName for disambiguation.

sandboxProvider*string|null
localAuthAvailable*boolean
localAuthAvailableSource*string
Value in"default""user_override"
terminalReason*|null
displayName*string

Stable user-facing session name; never render the raw session id as a label.

executionLocation*
spawnedBySessionId*|

The immediate parent session id for a spawned child session. Null for a root/human-launched session.

spawnRootSessionId*|

The ancestry root session id: self for a root launch, inherited unchanged for every descendant.

spawnDepth*integer

Absolute depth from the spawn root. 0 for a root/coordinator launch.

Range0 <= value <= 9007199254740991
relayRoomId*string|null
sessionDetail*
driverState*
recordingPolicy*string
recordingPointer*string|null
callerRole*string
Value in"driver""viewer"
wedgeState*
startedAt*string|null
endedAt*string|null
createdAt*string
updatedAt*string
Example Request
curl -X GET 'https://app.rensei.ai/api/interactive-sessions/string'
Example Response
{  "id": "string",  "sessionId": "string",  "orgId": "string",  "projectId": "string",  "createdByUserId": "string",  "status": "provisioning",  "liveStatus": "string",  "hostAlive": true,  "poolId": "string",  "poolName": "string",  "harness": "string",  "harnessName": "string",  "modelProfileId": "string",  "modelName": "string",  "modelSlug": "string",  "sandboxProvider": "string",  "localAuthAvailable": true,  "localAuthAvailableSource": "default",  "terminalReason": {    "code": "spawn_failed",    "message": "string",    "phase": "spawn",    "decidedBy": "runner",    "at": "2019-08-24T14:15:22Z"  },  "displayName": "string",  "executionLocation": {    "provider": "string",    "pool": {      "id": "string",      "displayName": "string"    },    "host": {      "id": "string",      "displayName": "string"    },    "sandboxFlavor": "string",    "runtimeFlavor": "string"  },  "spawnedBySessionId": "string",  "spawnRootSessionId": "string",  "spawnDepth": 0,  "relayRoomId": "string",  "sessionDetail": {    "property1": null,    "property2": null  },  "driverState": {    "property1": null,    "property2": null  },  "recordingPolicy": "string",  "recordingPointer": "string",  "callerRole": "driver",  "wedgeState": {    "state": "unknown",    "reason": "string",    "ptyFrozenMs": 0,    "deliveredNudgesSinceOutput": 0,    "cursorAdvancedSinceOutput": true,    "backPressure": "none",    "ptyOutputSeq": 0,    "ptyOutputAt": "string"  },  "startedAt": "string",  "endedAt": "string",  "createdAt": "string",  "updatedAt": "string"}

Launch a new interactive PTY-attach session.

Authentication accepts a browser session or a WorkOS user token; an rsk API key or a BYOA OAuth-agent token authenticates successfully but is rejected 403 because interactive sessions require a human user identity for driver/viewer grant derivation. Typed clients submit revision-pinned executionSelection refs from the project launch-options endpoint; stale, unavailable, unauthorized, or incompatible refs fail closed with 409. The repository, capacity pool, model profile, and harness axes are optional per axis: an axis the project has not configured is materialized at dispatch or omitted (the matching interactive_session_meta columns are nullable). Credential sets are resolved from project configuration, not a request axis: the canonical launch needs a resolvable default credential set, so a project with no visible credential set, several visible sets with no pinned default, or a stale pinned default that is no longer visible to the project refuses 409 (code=interactive_launch_credential_unavailable) before any workflow instance is created. Callers may omit executionSelection entirely and use the project/org default cascade; raw axis pins are rejected. When initialPrompt is supplied, the handler trims it and enforces an exact 1,023 UTF-8-byte limit without truncation. An optional workspace block (branchName/worktreeName/setupCommand) layers a bootstrap on top of the resolved repository axis; a non-empty bootstrap on a session with no resolved repository refuses 409 (code=INTERACTIVE_LAUNCH_NOT_CONFIGURED, reasonCode=WORKSPACE_BOOTSTRAP_NO_REPOSITORY) rather than being silently dropped. Entitlement-gated and quota-gated; never routes through MAB. An optional capabilities map lets the caller selectively disable a Composer-resolved capability/provider (memory, a2a, codeIntel, architecture, credential, issueTracker, kit, model); absent ⇒ everything the Composer resolved stays active. A machine principal (rsk key / OAuth agent) presenting a x-interactive-spawn-credential header carrying a valid spawn credential is routed to a separate machine-principal delegation path instead of the 403 above: gated behind the org's interactive_agent_spawn flag, a Cedar delegate_task permit, and a non-empty delegation policy on the credentialed parent session. The body is the smaller delegation shape (projectId, optional requestedCeiling/timeouts/initialPrompt/agentHandle/executionSelection/capabilities/workspace). A refusal returns the typed delegation envelope { code, class, message, axis?, limit?, current?, bindingLevel, bindingScopeId, retryAt?, remedy } - terminal/terminal_for_subtree classes as 403, retryable_when_child_exits/retryable_at as 429. A spawn body MAY additionally carry executionSelection (launch-axis intent refs: pool/harness/modelProfile/repository/agentCard StableExecutionRefs) and capabilities (memory scope / a2a handle). These are INTENT REFS ONLY, resolved through the exact same dispatchInteractiveSession cascade + admission gate the human launch path above uses - no new placement/selection authority. A viable ref outside the child's derived delegation ceiling still refuses (delegation_ceiling_violation) exactly as an omitted axis that resolved outside it always has.

Get durable A2A and host-heartbeat context for a live session.

A no-store pull snapshot for the collapsible live-session rail. Authentication accepts a browser session or WorkOS user token only. Returns 404 for absent, wrong-org, or inaccessible sessions so existence is not leaked. A2A messages come from the durable inbox; host telemetry comes from heartbeat rows; assignment exposes only closed state facts, never cloud/local provenance or ownership identity; continuity exposes only bounded adoption revisions, ordering timestamps, proof counts, release posture, lifecycle counters, and the newest live carrier handoff's non-secret credential facts (token-jti DIGEST, expiry, handoff revision). Raw worker, host, tenant, session, credential, timestamp, opaque-receipt, and cross-tenant identifiers are never included in assignment.