Reference

`chat`

Base path: /api/v1/chat

The chat module powers in-product conversational surfaces. It manages threads, messages, streaming responses over SSE, attachments, and the system context (brand knowledge, active agent) that shapes a conversation. Threads persist per workspace so users can resume sessions, and assistants have access to the same brand knowledge and connectors that agents do. Schemas live in app/modules/chat/schemas.py.

What you can do with the chat API

Start a thread bound to a specific agent or open-ended assistant
Append a user message and stream the assistant reply token-by-token
Resume an existing thread without losing system context
Attach knowledge documents or lead context to a message
List a user’s recent threads for sidebar UIs

Common operations

Create a thread (optionally seeded with system context)
Send a message and receive a streamed response
Fetch full thread history with timestamps and tool calls
Rename, pin, or archive a thread
Delete a thread and its messages
List threads for the current user, paginated by recency

Authentication & scoping

Workspace-scoped via API key in the Authorization: Bearer tnx_... header. Threads belong to a user inside a workspace, so cross-workspace access is blocked at the persistence layer.

Streaming

Replies stream over Server-Sent Events. Each event carries a delta, an optional tool-call envelope, and a final message ID. Clients should reconnect with the last seen event ID on disconnect.

Pagination & filtering

Thread and message lists paginate cursor-style. See Pagination.

How chat differs from agents

The agents module runs structured, typed crews with explicit input schemas. The chat module is open-ended, multi-turn, and conversational. Many chat threads can dispatch to an agent under the hood, but the surface and the persistence model are different.

MCP equivalents

MCP prompt

list_chat_threads({ user_id })