Mint a short-lived relay attach token (driver/viewer for users; host for the provisioning daemon) for an interactive session.
USER mint (role driver/viewer or omitted): 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 a role from). The minted role is a server-derived ceiling, never a client-claimed value. HOST mint (role "host"): accepts ONLY a worker-class machine identity - a plain org rsk_ API key or a worker runtime JWT - acting within the session's org; human identities, OAuth-agent tokens, and registration-bound keys are rejected 403. The host response carries the daemon wire contract { attachUrl, token, epoch, expiresAt } with a freshly allocated host stream epoch. HOST refresh (role "host-refresh", requires epoch): same caller gate as "host"; re-signs a token for the CURRENT host generation WITHOUT allocating a new epoch - the reconnect-after-expiry re-mint rail. A presented epoch that no longer matches the live generation is refused 409 (epoch_stale).
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).
application/json- body
role?stringRequested role. Omit to mint the caller's full derived USER capability. Requesting driver while only viewer-capable is rejected (403), never silently downgraded; requesting viewer while driver-capable downgrades. "host" is the daemon-facing provisioner mint — worker-class machine callers only; human identities are rejected (403). "host-refresh" re-signs a token for the CURRENT host generation (same epoch, no allocation) — the reconnect-after-expiry re-mint rail; requires epoch.
"driver""viewer""host""host-refresh"sseTicket?booleanUSER mint only: when true, the response additionally carries sseTicket — a single-use, ~30s, aud "relay-sse-ticket" JWT sharing the attach token's jti, presented as ?ticket= on the degraded SSE-down GET (the browser lane; EventSource cannot set headers). Invalid with role "host"/"host-refresh" (400).
epoch?integerThe live host generation's epoch, as minted. REQUIRED with role "host-refresh" (the refresh is refused 409 epoch_stale when it no longer matches the stored epoch); FORBIDDEN with any other role.
0 < value <= 9007199254740991Minted relay token. USER mint: { attachUrl, token, sseTicket? }. HOST mint: { attachUrl, token, epoch, expiresAt }.
application/json- response
attachUrl*stringtoken*stringsseTicket?stringcurl -X POST 'https://app.rensei.ai/api/interactive-sessions/string/tokens' \ -H 'Content-Type: application/json' \ -d '{}'{ "attachUrl": "string", "token": "string", "sseTicket": "string"}Cooperatively stop an interactive session.
Authentication accepts a browser session or a WorkOS user token only; an rsk API key or a BYOA OAuth-agent token is rejected 403. Idempotent-ish: stopping an already-ended session still returns 200 (the underlying Redis/SQL writes are themselves idempotent). 404 - never 403 - for a session belonging to a different org or one the caller has no project access for (no-existence-leak). Teardown drives the cooperative Redis/lock-refresh rail and, belt-and-braces, emits a fire-and-forget relay kill (reason: stopped) when the relay control env is configured. A session that is live on an ADOPTED session-shim lineage (its host daemon restarted and re-owned the harness) cannot be terminalized by the caller - the common release predicate holds its claim until the lineage's own terminal proof. For that case the stop is DELIVERED (relay kill toward the active carrier + the cooperative rail) and the route answers 202 with `stopped:false, delivered:true, pending:"terminal_evidence"`; the row flips to `ended` when the daemon posts the group-reaped tombstone. 409 is reserved for a hold nothing can deliver to (a restart hold window, or an unreconciled lineage): retry. A delivery the relay could not hand to a bound carrier is RE-SENT (on carrier re-attach, on the pty-nudge cycle, and on an interval from the reaper sweep) instead of being frozen behind the permanent stop stamp, and is bounded: the reaper terminalizes the row once the stop has stayed undelivered past its grace. `delivery.deliveryAttempts` / `delivery.lastDeliveryAt` report that progress. A machine principal presenting a x-interactive-spawn-credential header is routed to a separate machine-principal stop path instead of the 403 above, restricted to descendants in that credential's own spawn subtree. Unknown and cross-org targets return 404; a known same-org target outside the subtree is refused by Cedar. A refusal from credential/Cedar attestation returns the typed delegation envelope { code, class, message, axis?, limit?, current?, bindingLevel, bindingScopeId, retryAt?, remedy }.
List revision-pinned interactive-session launch choices for a project.
Human-only, project-authorized, redacted picker DTO for model profiles, profile-derived harnesses, capacity pools, repositories, and saved Agent Cards. Secret credentials, endpoint material, and raw resource configuration are never returned. The project must belong to the org resolved from the caller's auth context (default org, or an explicit org-selection header) - a projectId belonging to a different org 404s rather than being silently evaluated against the wrong org's profile/pool set.