Create or continue a chat with a streaming response
Create a chat with a specific agent, or continue an existing chat. Any document that you have access to that is in the agent’s knowledge base could be used to answer questions.
Rate Limits
600 requests per minute.
Approval-required events
If the agent reaches an ask-first action while streaming, the stream emits atool_approval_request event and then ends normally. Resume the paused chat with POST /chats/{chat_id}/approvals.
Tools, data analysis, and documents
Usetool_mode to set action behavior for one request. ask requires approval for every configured action, act allows configured actions to run without approval, and off disables all actions. Use tool_configs to override individual configured actions in ask or act mode. Use tool_connector_ids to select a subset of the agent’s configured external tools. These settings cannot add tools or change the agent’s saved configuration.
Set data_analysis to true to enable Data Analysis when the agent allows it, or false to disable it for this request. Omit the field to use the agent’s configured default. Use document_refs to attach up to 20 exact documents by Realm API data source ID and source document ID. Realm checks that the API token’s user can access each document before starting the stream.
One answer at a time per chat
A chat answers one message at a time. If you send a request for achat_id that is still generating an answer, Realm refuses the second turn rather than running both and losing one of the answers.
The stream has already started by the time Realm knows about the conflict, so it arrives as a terminal generation_error event with an error of generation_in_flight and a retry_after_seconds field holding the number of seconds the in-flight answer may still run. The stream then ends. Wait that long and retry, or omit chat_id to start a separate chat. Requests for different chats never conflict with each other.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
The content of the user message.
Deprecated. Use agent_id instead.
The ID of the chat to continue. If not provided, a new chat will be created.
"123"
Enable research mode for this chat. Only works if the agent has research mode enabled ('optional' or 'always_on').
Control Data Analysis for this request. Omit to use the agent's configured default, set true to enable it when allowed, or set false to disable it for this request.
Attach exact documents by Realm API data source ID and source document ID.
20The style of citations to use. 'remove' will not show any citations, 'link' will format them as URLs.
link, remove The format of the content returned. 'markdown' includes formatting, 'text' returns plain text.
markdown, text Prompt variables as input to the agent.
When enabled for non-streaming responses, return only the final answer text, excluding intermediate reasoning, thinking steps, and agent narration. Has no effect on streaming responses.
Experimental. Use cost-efficient models for this request. Omit to inherit the agent and organization defaults. Eco is available only for Auto and Smart agents.
Set action behavior for this request. Ask requires approval for every available action, act skips approval for available actions, and off disables all actions.
ask, act, off Replace the agent's configured external tools with these connector or action identifiers for this request.
1001Override ask, enabled, or disabled status for individual available actions. Overrides take precedence over ask or act mode; off always disables actions.

