PATCH/api/v1/flows/{flowId}/sessions/{sessionId}/config
Replaces a live session’s configuration without restarting it.
Exists because a warm session outlives a short-lived credential. A session can hold a container for an hour; a tenant-scoped bearer token is often good for rather less, and without rotation the choice is to let the session break or to issue a long-lived token — which is the thing per-session scoping is meant to avoid.
Replaces rather than merges. A partial update of a security boundary is a way to leave half a policy in force, so send the whole configuration each time.
Takes effect on the next turn. A turn already running finishes under the configuration it started with.
delivered: false is not an error — a sleeping session has no container
to push to and picks the new configuration up when the next message
wakes it.
Authentication
Requires a project API key — see Authentication.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
flowId | path | string | required | UUID of the flow to trigger. |
sessionId | path | string | required |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
mcpServers | object | optional | MCP servers scoped to this run or session. Remote transports only (http, sse); TLS required off localhost. |
mcpMode | string (merge | replace) | optional |
appendSystemPrompt | string | optional | |
disallowedTools | array | optional | |
env | object | optional | |
partialMessages | boolean | optional |
Responses
| Status | Description |
|---|---|
200 | Configuration stored. |
400 | Request body or query parameters failed validation. |
404 | Flow or session not found. |
Tag: Chat