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.
AuthorizationBearer <rsk_live_*>Rensei API key presented as Authorization: Bearer rsk_live_. Required API-key scopes are recorded per operation in x-rensei-required-scopes.
id*stringThe session id (agent_sessions.session_id).
Session detail.
application/json- response
id*stringsessionId*stringorgId*stringprojectId*stringcreatedByUserId*string|nullstatus*string"provisioning""active""paused""ended""failed"liveStatus*string|nullhostAlive*|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|nullpoolName*|Human-readable workarea/pool name resolved server-side; falls back to poolId only when the referent is gone.
harness*string|nullharnessName*|Human-readable harness name resolved server-side; falls back to harness only when the referent is gone.
modelProfileId*string|nullmodelName*|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|nulllocalAuthAvailable*booleanlocalAuthAvailableSource*string"default""user_override"terminalReason*|nulldisplayName*stringStable 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*integerAbsolute depth from the spawn root. 0 for a root/coordinator launch.
0 <= value <= 9007199254740991relayRoomId*string|nullsessionDetail*driverState*recordingPolicy*stringrecordingPointer*string|nullcallerRole*string"driver""viewer"wedgeState*startedAt*string|nullendedAt*string|nullcreatedAt*stringupdatedAt*stringcurl -X GET 'https://app.rensei.ai/api/interactive-sessions/string'{ "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.