> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryopencomputer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Text chat sessions and streaming

> Create authenticated workflow sessions, stream turns, and recover safely.

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](/guides/website.md).

## 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.

```json theme={null}
{
  "request_id": "4df0c1de-d140-4a84-a35d-96c4bdb60455",
  "name": "Synthetic support conversation",
  "initial_context": {
    "customer_name": "Sam Example",
    "case_reference": "CASE-EXAMPLE-001"
  }
}
```

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:

```text theme={null}
GET /api/v1/workflow/{workflow_id}/text-chat/sessions/recovery/{request_id}
```

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:

```text theme={null}
GET /api/v1/workflow/{workflow_id}/text-chat/sessions/{run_id}
```

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`:

```json theme={null}
{
  "text": "I need help with case CASE-EXAMPLE-001.",
  "expected_revision": 1
}
```

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:

| Action | Path |
| - | - |
| Create and stream a session | `POST /api/v1/workflow/{workflow_id}/text-chat/sessions/stream` |
| Append and stream a message | `POST /api/v1/workflow/{workflow_id}/text-chat/sessions/{run_id}/messages/stream` |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.