Create or continue a chat

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.

POST /chats

Create or continue a chat

cURL

curl --request POST \
  --url https://{subdomain}.withrealm.com/api/external/alpha/chats \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "content": "<string>",
  "assistant_id": "<string>",
  "agent_id": "<string>",
  "chat_id": "123",
  "research_mode": false,
  "citation_style": "remove",
  "output_format": "markdown",
  "prompt_variables": {},
  "answer_only": false
}
'

200

{
  "assistant_id": "<string>",
  "agent_id": "<string>",
  "created": 123,
  "created_date": "<string>",
  "content": "<string>",
  "research_mode": true,
  "output_format": "markdown",
  "status": "completed",
  "id": "<string>"
}

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 · default: false

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.

Show child attributes

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

200

application/json

Success

Option 1

Option 2

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

The chat completed successfully

Available options: completed

id · string

Unique identifier for the chat