Skip to main content
POST
/
chats
Error
A valid request URL is required to generate request examples
{
  "id": "<string>",
  "assistant_id": "<string>",
  "agent_id": "<string>",
  "created": 123,
  "created_date": "<string>",
  "content": "<string>",
  "research_mode": true
}

Documentation Index

Fetch the complete documentation index at: https://docs.withrealm.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Approval-required responses

If the agent reaches an ask-first action, this endpoint returns 200 OK with status: "approval_required" instead of failing. Use the returned assistant_message_id and approval metadata to resume the chat via POST /chats/{chat_id}/approvals.

​
Rate Limits

600 requests per minute.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
content
string
required

The content of the user message.

​
assistant_id
string | null

Deprecated. Use agent_id instead.

​
agent_id
string | null

The ID of the agent to use for the chat. You can find the ID by clicking on the agent in the Agents page.

​
chat_id
string

The ID of the chat to continue. If not provided, a new chat will be created.

Example:

"123"

​
research_mode
boolean

Enable research mode for this chat. Only works if the agent has research mode enabled ('optional' or 'always_on').

​
citation_style
enum<string>
default:remove

The style of citations to use. 'remove' will not show any citations, 'link' will format them as URLs.

Available options:
link,
remove
​
output_format
enum<string>
default:markdown

The format of the content returned. 'markdown' includes formatting, 'text' returns plain text.

Available options:
markdown,
text
​
prompt_variables
object

Prompt variables as input to the agent.

​
answer_only
boolean
default:false

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.

Response

Success

​
id
string
required

Unique identifier for the chat

​
assistant_id
string
required

Deprecated. Use agent_id instead.

​
agent_id
string
required

The ID of the agent that processed the request

​
created
number
required

Unix timestamp in milliseconds of when the completion was created

​
created_date
string
required

ISO 8601 formatted timestamp of when the completion was created

​
content
string
required

The content of the chat

​
research_mode
boolean
required

If research mode was used for this chat. The agent configuration can override the user requested value.

​
output_format
enum<string>
required

The format of the content returned

Available options:
markdown,
text
​
status
enum<string>
required

Whether the chat completed immediately or was queued

Available options:
completed,
queued