curl --request POST \
--url https://app.withrealm.com/api/external/alpha/chats-streaming \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agent_id": "agt_1a2b3c",
"content": "Summarize our Q3 sales performance.",
"chat_id": "cht_9x8y7z",
"tool_mode": "ask",
"document_refs": [
{
"data_source_id": "ds_kb_main",
"source_id": "doc_42"
}
],
"citation_style": "link",
"output_format": "markdown"
}
'import requests
url = "https://app.withrealm.com/api/external/alpha/chats-streaming"
payload = {
"agent_id": "agt_1a2b3c",
"content": "Summarize our Q3 sales performance.",
"chat_id": "cht_9x8y7z",
"tool_mode": "ask",
"document_refs": [
{
"data_source_id": "ds_kb_main",
"source_id": "doc_42"
}
],
"citation_style": "link",
"output_format": "markdown"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: 'agt_1a2b3c',
content: 'Summarize our Q3 sales performance.',
chat_id: 'cht_9x8y7z',
tool_mode: 'ask',
document_refs: [{data_source_id: 'ds_kb_main', source_id: 'doc_42'}],
citation_style: 'link',
output_format: 'markdown'
})
};
fetch('https://app.withrealm.com/api/external/alpha/chats-streaming', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.withrealm.com/api/external/alpha/chats-streaming"
payload := strings.NewReader("{\n \"agent_id\": \"agt_1a2b3c\",\n \"content\": \"Summarize our Q3 sales performance.\",\n \"chat_id\": \"cht_9x8y7z\",\n \"tool_mode\": \"ask\",\n \"document_refs\": [\n {\n \"data_source_id\": \"ds_kb_main\",\n \"source_id\": \"doc_42\"\n }\n ],\n \"citation_style\": \"link\",\n \"output_format\": \"markdown\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://app.withrealm.com/api/external/alpha/chats-streaming")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent_id\": \"agt_1a2b3c\",\n \"content\": \"Summarize our Q3 sales performance.\",\n \"chat_id\": \"cht_9x8y7z\",\n \"tool_mode\": \"ask\",\n \"document_refs\": [\n {\n \"data_source_id\": \"ds_kb_main\",\n \"source_id\": \"doc_42\"\n }\n ],\n \"citation_style\": \"link\",\n \"output_format\": \"markdown\"\n}"
response = http.request(request)
puts response.read_body<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.withrealm.com/api/external/alpha/chats-streaming",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent_id' => 'agt_1a2b3c',
'content' => 'Summarize our Q3 sales performance.',
'chat_id' => 'cht_9x8y7z',
'tool_mode' => 'ask',
'document_refs' => [
[
'data_source_id' => 'ds_kb_main',
'source_id' => 'doc_42'
]
],
'citation_style' => 'link',
'output_format' => 'markdown'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"type": "generation_tokens",
"text": "Your Q3 revenue grew ",
"id": "cht_9x8y7z",
"full": false
}{
"error": "<string>",
"details": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}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.
curl --request POST \
--url https://app.withrealm.com/api/external/alpha/chats-streaming \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agent_id": "agt_1a2b3c",
"content": "Summarize our Q3 sales performance.",
"chat_id": "cht_9x8y7z",
"tool_mode": "ask",
"document_refs": [
{
"data_source_id": "ds_kb_main",
"source_id": "doc_42"
}
],
"citation_style": "link",
"output_format": "markdown"
}
'import requests
url = "https://app.withrealm.com/api/external/alpha/chats-streaming"
payload = {
"agent_id": "agt_1a2b3c",
"content": "Summarize our Q3 sales performance.",
"chat_id": "cht_9x8y7z",
"tool_mode": "ask",
"document_refs": [
{
"data_source_id": "ds_kb_main",
"source_id": "doc_42"
}
],
"citation_style": "link",
"output_format": "markdown"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: 'agt_1a2b3c',
content: 'Summarize our Q3 sales performance.',
chat_id: 'cht_9x8y7z',
tool_mode: 'ask',
document_refs: [{data_source_id: 'ds_kb_main', source_id: 'doc_42'}],
citation_style: 'link',
output_format: 'markdown'
})
};
fetch('https://app.withrealm.com/api/external/alpha/chats-streaming', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.withrealm.com/api/external/alpha/chats-streaming"
payload := strings.NewReader("{\n \"agent_id\": \"agt_1a2b3c\",\n \"content\": \"Summarize our Q3 sales performance.\",\n \"chat_id\": \"cht_9x8y7z\",\n \"tool_mode\": \"ask\",\n \"document_refs\": [\n {\n \"data_source_id\": \"ds_kb_main\",\n \"source_id\": \"doc_42\"\n }\n ],\n \"citation_style\": \"link\",\n \"output_format\": \"markdown\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://app.withrealm.com/api/external/alpha/chats-streaming")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent_id\": \"agt_1a2b3c\",\n \"content\": \"Summarize our Q3 sales performance.\",\n \"chat_id\": \"cht_9x8y7z\",\n \"tool_mode\": \"ask\",\n \"document_refs\": [\n {\n \"data_source_id\": \"ds_kb_main\",\n \"source_id\": \"doc_42\"\n }\n ],\n \"citation_style\": \"link\",\n \"output_format\": \"markdown\"\n}"
response = http.request(request)
puts response.read_body<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.withrealm.com/api/external/alpha/chats-streaming",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent_id' => 'agt_1a2b3c',
'content' => 'Summarize our Q3 sales performance.',
'chat_id' => 'cht_9x8y7z',
'tool_mode' => 'ask',
'document_refs' => [
[
'data_source_id' => 'ds_kb_main',
'source_id' => 'doc_42'
]
],
'citation_style' => 'link',
'output_format' => 'markdown'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"type": "generation_tokens",
"text": "Your Q3 revenue grew ",
"id": "cht_9x8y7z",
"full": false
}{
"error": "<string>",
"details": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}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 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.
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').
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 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.
Hide child attributes
Hide child attributes
Return a normalized persisted trace for the current turn, including approval pauses. Requires internal evaluation access.
Force the primary agent and answer model for a controlled evaluation. Shared classifier and search helper models remain unchanged. Requires include_turn_trace.
test, o1, o3, o1-mini, o3-mini, o4-mini, gpt-image-2, azure-gpt-5.6-terra-credits, azure-gpt-5.6-luna-credits, gpt-5.6-luna, gpt-5.6-luna-eu, azure-gpt-5.5-credits, azure-gpt-5.4-credits, azure-gpt-5.4-mini-credits, azure-gpt-5.1-credits, azure-finetuned-mini-1, azure-finetuned-filtersearch-1, azure-finetuned-filtersearch-2, azure-finetuned-filtersearch-3, vertex-finetuned-1, vertex-finetuned-2, azure-o1, azure-o3, azure-o1-mini, azure-o3-mini, azure-o4-mini, vertex-claude-3-7-sonnet@20250219, vertex-claude-3-5-sonnet@20240620, vertex-claude-3-5-sonnet-v2@20241022, vertex-claude-3-haiku@20240307, vertex-claude-3-opus@20240229, vertex-claude-opus-4@20250514, vertex-claude-sonnet-4@20250514, vertex-claude-sonnet-4-5@20250929, vertex-claude-opus-4-5@20251101, vertex-claude-opus-4-6@default, vertex-claude-opus-4-7@global, vertex-claude-opus-4-7@eu, vertex-claude-sonnet-5@eu, vertex-claude-opus-4-8@global, vertex-claude-opus-4-8@eu, vertex-claude-opus-5@global, vertex-claude-opus-5@eu, vertex-claude-sonnet-4-6, vertex-claude-haiku-4-5@20251001, bedrock-anthropic.claude-opus-4-5-20251101-v1:0, bedrock-anthropic.claude-opus-4-6-v1, bedrock-anthropic.claude-opus-4-7, bedrock-anthropic.claude-opus-4-8, bedrock-anthropic.claude-opus-5, bedrock-anthropic.claude-sonnet-4-6, bedrock-anthropic.claude-sonnet-4-5-20250929-v1:0, bedrock-us-anthropic.claude-sonnet-4-20250514-v1:0, bedrock-eu-anthropic.claude-sonnet-4-20250514-v1:0, bedrock-eu-anthropic.claude-3-7-sonnet-20250219-v1:0, bedrock-eu-anthropic.claude-3-5-sonnet-20240620-v1:0, bedrock-eu-anthropic.claude-3-5-haiku-20241022-v1:0, bedrock-anthropic.claude-haiku-4-5-20251001-v1:0, claude-sonnet-4-20250514, claude-sonnet-4-6, claude-sonnet-5, claude-opus-4-6, claude-opus-4-7, claude-opus-4-8, claude-opus-5, claude-haiku-4-5-20251001, claude-sonnet-4-5-20250929, claude-3-7-sonnet-latest, claude-3-7-sonnet-20250219, claude-3-5-sonnet-20241022, groq-mixtral, google-gemini-1.5-pro-001, google-gemini-1.5-flash-001, google-gemini-2.0-flash-001, google-gemini-2.5-pro, google-gemini-2.5-flash, google-gemini-2.5-flash-lite, google-gemini-2.5-flash-image, google-gemini-3.1-flash-lite, google-gemini-3.1-flash-lite-eu, google-gemini-3.1-flash-image, google-gemini-3.5-flash-lite, google-gemini-3.5-flash-lite-eu, google-gemini-3.5-flash, google-gemini-3.5-flash-eu, google-gemini-3.6-flash, google-gemini-3.7-flash, google-gemini-3.7-flash-eu, google-gemini-3.8-flash, google-gemini-3.8-flash-eu, gemini-2.0-flash-001, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.5-flash-image, gemini-3.1-flash-lite, gemini-3.1-flash-image, gemini-3.5-flash-lite, gemini-3.5-flash, gemini-3.6-flash, gemini-3.7-flash, gemini-3.8-flash, gemini-3-pro, gemini-3-flash, google-gemini-3-flash, google-gemini-3-pro, finetuned-mini, finetuned-mini-2, finetuned-mini-3, finetuned-filtersearch-1, finetuned-gpt41mini-1, finetuned-4o, qwen-7b, flow-judge, llama-3.2-3b, cerebras-llama-3.3-70b, nebius-kimi-k2.5, nebius-gpt-oss-120b, nebius-gpt-oss-20b, nebius-qwen3-30b-thinking, nebius-nemotron-nano-30b, nebius-glm-4.5-air, nebius-minimax-m2.1, nebius-deepseek-v4-flash, nebius-deepseek-v4-flash-0731, azure-deepseek-v4-flash, azure-deepseek-v4-flash-0731, tensorx-deepseek-v4-flash, tensorx-deepseek-v4-flash-0731, tensorx-qwen3.8-flash-next, scaleway-deepseek-v4-flash-0731, lyceum-deepseek-v4-flash-0731, lyceum-qwen3.8-flash-next, fireworks-deepseek-v4-flash-0731, baseten-deepseek-v4-flash-0731, gmicloud-deepseek-v4-flash, gmicloud-qwen3.8-flash, deepinfra-deepseek-v4-flash, deepinfra-deepseek-v4-flash-0731, digitalocean-deepseek-v4-flash-0731, deepseek-v4-1-flash, novita-deepseek-v4-1-flash, deepinfra-deepseek-v4-1-flash, fireworks-deepseek-v4-1-flash, gmicloud-deepseek-v4-1-flash, baseten-deepseek-v4-1-flash, digitalocean-deepseek-v4-1-flash, tensorx-deepseek-v4-1-flash, digitalocean-mimo-v2.5, deepinfra-mimo-v2.5, deepinfra-minimax-m3, deepinfra-hy3, deepinfra-step-3.7-flash Force a provider-neutral reasoning effort for primary model calls in a controlled evaluation. Max resolves to the strongest setting supported by each concrete model and provider. Requires include_turn_trace.
low, medium, high, max 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.

