POST/api/v1/flows/{flowId}/chat
The structured chat interface — send a message to a flow and receive the
assistant’s reply. This is distinct from /runs: it drives the flow via
the resume-per-message chat engine (the same one behind the Portal and
Slack), not the raw terminal.
Pass a stable sessionId to continue a conversation — the flow resumes
the same session (history + working directory) for that id. Omit it and a
new sessionId is generated and returned; reuse it on the next call.
The first message for a session cold-starts a container, so expect a few seconds of latency; subsequent messages on a warm session are fast.
Blocking or streaming
By default this blocks until the turn finishes, and gives up after 120
seconds — returning whatever had arrived with truncated: true. Check
that field: a truncated reply frequently reads as a finished one, and
the flow keeps running behind it.
Pass stream: true to get 202 at once and read the turn from the
session’s SSE stream instead. There is no deadline on that path. Pair it
with POST /flows/{flowId}/sessions so the stream is open before the
first message.
Authentication
Requires a project API key — see Authentication.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
flowId | path | string | required | UUID of the flow to trigger. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
message | string | required | The user message to send to the flow. |
sessionId | string | optional | Stable conversation id. Reuse it across calls to continue the same conversation (the flow resumes that session). If omitted, a new one is generated and returned in the response. |
stream | boolean | optional | Acknowledge immediately with 202 and deliver the turn on the session’s SSE stream instead of blocking. Prefer this for anything that might take a while. The blocking form has to decide when to stop waiting; the streaming form does not, because output is already reaching you. |
Responses
| Status | Description |
|---|---|
200 | Reply generated. |
400 | Request body or query parameters failed validation. |
401 | Missing, malformed, expired, or revoked API key. |
404 | Resource not found or not accessible to this project. |
429 | Rate limit exceeded. |
Tag: Chat