Skip to main content
Use the text-chat API when your trusted backend needs to create and manage a text conversation for a workflow. Requests use your organization’s X-API-Key; keep that key on the server. Creating a session or sending a message starts workflow execution and may use model quota or invoke tools. Text-chat sessions use a numeric workflow_id and return a numeric workflow_run_id (also called run_id). They are distinct from public website-widget sessions, which use an embed token and a short-lived session token. For the widget path, see Embed an agent on your website.

​
Create and read a session

Create a session with POST /api/v1/workflow/{workflow_id}/text-chat/sessions. The request can include initial_context, an optional name, and a client-generated UUID request_id. Keep the request ID until you have the response; if the response is lost, use the recovery endpoint to find the created session rather than blindly creating another one.
The response includes the workflow_run_id, current revision, and session state. Use the run ID to read the current session or open its run details. If creation returned no response, recover with:
A recovery result may be null if the session is not visible yet. Check again before attempting to create another session. The regular read path is:
An initial turn can contain no visible assistant text. Render the messages that are present and allow the visitor to send the first message; a successful creation response does not guarantee an opening greeting.

​
Send a message

Append a message with POST /api/v1/workflow/{workflow_id}/text-chat/sessions/{run_id}/messages:
Pass the latest revision you read from the session response. This guards against two clients updating an out-of-date conversation. If the response is 409, read the session again: the revision may have changed, or a turn may already be running. Do not resend the same message until you have checked the current transcript, because tool actions from the first request may already have run.

​
Stream a turn with SSE

Session creation and message submission have streaming variants: The response is server-sent events: parse data: frames and handle the session, turn_event, complete, and error event types. The stream starts with a POST body, so a browser client typically uses fetch and reads its response stream; ordinary EventSource opens a GET and cannot send the request body. The response includes X-Workflow-Run-Id so a client can recover the run even if it disconnects before reading the first event. Treat the stream as a sequence of events, not a single final JSON object. If the client disconnects, use the run ID or original creation request_id to read the session state before sending another message.

​
Rewind and end

Use POST /api/v1/workflow/{workflow_id}/text-chat/sessions/{run_id}/rewind to set the active conversation cursor to an earlier turn. Provide cursor_turn_id for the turn to resume from and the current expected_revision. A missing or invalid turn returns 404; a stale revision or turn in progress can return 409. After rewinding, a new message continues from that point and later turns leave the active path. End a session with POST /api/v1/workflow/{workflow_id}/text-chat/sessions/{run_id}/end, including the current expected_revision. Ended sessions cannot accept further messages. Use rewind only when you intend to change the active conversation path; it is not a way to delete or conceal a recorded run.

​
How public embeds differ

The authenticated workflow API uses workflow_id, run_id, and your API key. A public embed first calls /api/v1/public/embed/init or /init/stream with an embed token, then uses the returned session token for message requests. The public embed stream is limited to visitor-facing response content and does not expose private tool results or internal workflow errors. Do not put an API key in a web page to make the authenticated API available to a visitor. Use the generated widget unless you need to own the browser chat interface. For either path, verify the full session lifecycle in the target application and organization before launch; route availability alone does not prove a successful model-backed conversation.