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.
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.
application/json- body
continuity?projectId*stringThe project to launch the interactive session in.
1 <= lengthexecutionSelection?Partial revision-pinned picker evidence. Shared dispatch resolves omitted axes and admits the complete effective selection.
poolId?stringPin the capacity pool. Omit to use the project/org primary sandbox resource.
1 <= lengthharness?stringPin the runtime harness (e.g. claude, codex). Omit to use the resolved model profile's harness.
1 <= lengthmodelProfileId?stringPin the model profile. Omit to use the normal project/org/system cascade.
1 <= lengthrepositoryId?integerPin project_repositories.id. Omit to use the project's primary repo.
0 < value <= 9007199254740991sandboxProvider?stringPin the sandbox provider. Omit to use the project default.
1 <= lengthtimeouts?localAuthAvailable?booleanExplicit local-auth availability choice. Omit for the declared-pool/session-type default.
initialPrompt?stringOptional seed prompt. The exact limit is 1,023 UTF-8 bytes after trimming; OpenAPI maxLength is only a coarse character bound, and the handler performs the authoritative byte measurement without truncation. Stamped onto the dispatched work payload; the runner injects it as the session's first input once the terminal is up. Omit the field or submit a blank string to start a blank session.
length <= 1023mailbox?string"resume""resume""fresh"agentHandle?stringDurable, typable name for this session (e.g. "cfo", "chief-of-staff"). Mints/reuses an agent identity unique per organization and stamps it on the session, which is what makes the session addressable by peers: it appears in a2a_list_agents and a2a_send_message resolves this handle to this session. Omit to launch an unaddressable session.
1 <= length <= 64issueIdentifier?stringOptional tracker issue this session works on (e.g. "ABC-123"). Proven inside the launching project's tracker binding; a foreign issue refuses 409. Omit or blank for an unbound session.
1 <= length <= 32label?stringOptional short human label for this session (e.g. "review seat 3"). Trimmed, capped at 64 chars, stored on metadata + session_detail and returned by the list read. Omit or blank for none.
1 <= length <= 64capabilities?Launch-time capability/provider enablement (memory, a2a, codeIntel, architecture, credential, issueTracker, kit, model). Absent key or absent field ⇒ enabled — only an explicit false disables a Composer-resolved capability/provider for this session.
workspace?Workspace bootstrap (branchName/worktreeName/setupCommand), layered on top of the resolved repository axis — never a substitute for it. Requires a resolved repository: a non-empty bootstrap on a repo-less session refuses 409 (code=INTERACTIVE_LAUNCH_NOT_CONFIGURED, reasonCode=WORKSPACE_BOOTSTRAP_NO_REPOSITORY) rather than being silently dropped. Omit for no bootstrap.
Session dispatched.
application/json- response
sessionId*stringmetaId*stringstatus*stringlocalAuthAvailable*booleanlocalAuthAvailableSource*string"default""user_override"advisory?degraded?booleanTrue when this session was admitted while Redis was unavailable: durable rows exist (quota consumed, session rows committed) but delivery (session-state store + work-queue enqueue) was deferred, so the session cannot yet be attached to or claimed by a worker. Absent/false on a normal, fully-delivered launch.
initialPromptEnqueued?booleanTrue when a seed prompt was enqueued on the dispatched work payload. Absent when no initialPrompt was supplied.
curl -X POST 'https://app.rensei.ai/api/interactive-sessions' \ -H 'Content-Type: application/json' \ -d '{ "projectId": "string"}'{ "sessionId": "string", "metaId": "string", "status": "provisioning", "localAuthAvailable": true, "localAuthAvailableSource": "default", "advisory": { "code": "LOCAL_AUTH_EPHEMERAL_HEADLESS_PROVIDER_ADVISORY", "message": "string" }, "degraded": true, "initialPromptEnqueued": true}List interactive sessions visible to the caller.
Browser sessions and WorkOS user tokens list projects visible through their roles (org admins see all). API keys and BYOA OAuth-agent tokens require a non-null effective project fence, intersecting key and registration restrictions; unfenced machine principals are refused. `?project=<slug>` or `?projectId=<id>` narrows the list to one project; an inaccessible or out-of-fence project returns an empty list. Every list remains scoped to the authenticated org.
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.