Open a conversation without sending a message

POST /api/v1/flows/{flowId}/sessions

Creates or resolves a chat session and returns its streamUrl, without running anything.

This exists so you can be reading the stream before the first message produces output. Otherwise turn one is the only turn you cannot watch live: every later message can use the stream opened by its predecessor, but the first would have to race container start-up.

The stream belongs to the session, not the turn — streamUrl stays valid for every message that follows, because the session’s runId does not change.

Per-session configuration

The same fields the run trigger accepts — mcpServers, mcpMode, appendSystemPrompt, disallowedTools, env — apply here, scoped to this session’s container. That is how one flow serves many tenants over a warm, persistent session: give the session its own MCP server and a tenant-scoped token, and withhold write tools with disallowedTools.

The lifetime differs from a run. A run consumes its configuration on first boot; a session keeps it. A session outlives its container — idle after 5 minutes unattended, 60 with the stream held open, then respawned by the next message — and a consumed config would bring that container back with no MCP servers and no disallowedTools, silently dropping both the tenant scoping and the “cannot call write tools” guarantee mid-conversation.

Rotate a short-lived credential with PATCH /flows/{flowId}/sessions/{sessionId}/config.

POST /flows/{id}/sessions        → { sessionId, runId, streamUrl }
GET  {streamUrl}                 → open it, leave it open
POST /flows/{id}/chat            → { message, sessionId, stream: true }
                                   202; output arrives on the stream
POST /flows/{id}/chat            → next turn, same stream

Authentication

Requires a project API key — see Authentication.

Parameters

Request body

Responses

Tag: Chat