Rensei docs
API ReferenceInteractive sessions

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. When initialPrompt is supplied, the handler trims it and enforces an exact 1,023 UTF-8-byte limit without truncation; the schema maxLength is only a coarse character bound. Entitlement-gated (403 when the org lacks the interactive_sessions feature flag) and quota-gated (429 with {code, limit, current} when the org is at its concurrent-inflight or monthly-attached-seconds cap). Unpinned axes (poolId, harness, modelProfileId, repositoryId, sandboxProvider) resolve through the project/org default cascade - this path never routes through MAB.

POST
/api/interactive-sessions

Authorization

AuthorizationBearer <token>

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

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/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"
  },
  "initialPromptEnqueued": true
}
Empty
Empty
Empty
Empty
Empty
Empty
Empty

List interactive sessions visible to the caller.

Same auth posture as POST: session/user_token only. `?project=<slug>` or `?projectId=<id>` scopes to one project (gated by checkInteractiveAccess - an inaccessible project returns an empty list, not an error). Omitted, the list is scoped to every project the caller can see in the org (org admins see all).

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.