Chat API Reference

This page documents the request and response schemas for the Chat API. For endpoint URLs and quickstart examples, see Getting Started.

Request Schema

Both the streaming (POST /chat/stream) and non-streaming (POST /chat/response) endpoints accept the same request body:

{
  "agent_identifier": "string (required)",
  "conversation": [ChatMessage],
  "conversation_context": ConversationContext,
  "bot_params": {}
}

Field	Type	Required	Description
agent_identifier	string	Yes	The identifier of the agent to invoke
conversation	ChatMessage[]	Yes	The conversation history
conversation_context	ConversationContext	No	Top-level context for the request
bot_params	object	No	Runtime parameters for the agent (see below)

ChatMessage

A single message in the conversation. The sender field is "user" for user messages and "bot" for agent messages:

{
  "sender": "user" | "bot",
  "content": "string",
  "message_id": "string",
  "content_parts": [ContentPart],
  "evidences": [ChatMessageEvidence],
  "function_call_request": FunctionCallRequest,
  "function_call_response": FunctionCallResponse,
  "function_specs": FunctionSpec,
  "image_uri": "string"
}

Field	Type	Required	Description
sender	"user" or "bot"	Yes	Message author — "bot" denotes the agent's response
content	string	Yes	The text content of the message
message_id	string	No	Unique message identifier (returned by server; used for feedback)
content_parts	ContentPart[]	No	Structured message parts (context, text, tool calls, tables)
evidences	ChatMessageEvidence[]	No	Citation evidence linking answer spans to sources
function_call_request	object	No	Deprecated. Legacy function call suggestion — use tool content parts instead
function_call_response	object	No	Deprecated. Legacy function call result — use tool content parts instead
function_specs	object	No	Deprecated. Function specifications for legacy function call pattern
image_uri	string	No	Deprecated. Use content parts for media

ContentPart

Each content part has a type discriminator and one corresponding data field:

Type	Data Field	Description
"text"	text	A text segment of the agent's response
"context"	context	A ConversationContext block (documents the agent found or context the client attached)
"tool"	tool	A tool call event with lifecycle status
"table"	table	Structured tabular data

{
  "type": "text" | "context" | "tool" | "table",
  "text": "string",
  "context": ConversationContext,
  "tool": ContentPartTool,
  "table": ContentPartTable
}

ContentPartTool

Represents a single tool call and its lifecycle. Agents stream these to communicate what they are doing:

Field	Type	Required	Description
tool_call_id	string	Yes	Unique identifier for this tool invocation
name	string	Yes	Name of the tool being called
params	object	No	Visible parameters sent to the tool
response	object	No	Tool execution result (present when completed)
display_text	string	No	Human-readable description of what the tool is doing/did
status	"running" / "completed" / "error"	No	Current lifecycle state

See Content Parts for how to render these in a UI.

ContentPartTable

Structured tabular data returned by an agent:

Field	Type	Description
format	"row" or "columnar"	How the data is organized
headers	string[]	Column headers
rows	object[]	Row data (when format is "row") — each object maps header → value
columns	object	Column data (when format is "columnar") — maps header → value[]

Exactly one of rows or columns must be present.

Example (row format):

{
  "type": "table",
  "table": {
    "format": "row",
    "headers": ["Document", "Relevance"],
    "rows": [
      {"Document": "BERT paper", "Relevance": "High"},
      {"Document": "GPT-2 paper", "Relevance": "Medium"}
    ]
  }
}

ConversationContext

Context scoping the conversation to specific documents, tags, filters, or custom content. Can appear at the top level of the request or inside a content_parts entry with type: "context".

{
  "document_context": {
    "document_ids": ["string"],
    "retrieval_unit": "document" | "chunk"
  },
  "custom_context": {
    "items": [
      {"document_id": "string", "content": "string or object"}
    ]
  },
  "tag_context": {
    "tag_ids": ["string"]
  },
  "filter_context": {
    "filters": {}
  },
  "user_document_context": {
    "enabled": true
  }
}

document_context and custom_context are mutually exclusive. All other fields can be combined freely.

See Passing Context for usage patterns and examples.

ChatMessageEvidence

A citation linking a span of the answer to a source document:

Field	Type	Required	Description
document_hit_url	string	Yes	URL path to fetch the source document/chunk
text_extract	string	No	Relevant passage from the source (with <b> highlights)
anchor_text	string	No	The citation marker in the answer text (e.g., <sup>1</sup>)

See Handling Citations for rendering patterns.

Response Schema

Non-Streaming Response (ChatResponseItem)

{
  "agent_identifier": "string",
  "conversation": [ChatMessage],
  "conversation_context": ConversationContext,
  "function_specs": [FunctionSpec]
}

The response echoes back the full conversation with the agent's response appended as the last message.

Streaming Response (SSE)

The streaming endpoint returns Server-Sent Events. Each event has:

event: new_message
id: {message_id}:{event_index}
data: {ChatMessage as JSON}
retry: 15000

Each event contains the complete message so far — as tokens are generated, the content field grows incrementally. The final event contains the fully formed response including evidences and content_parts.

See Streaming for reconnection, cancellation, and protocol details.

bot_params

The bot_params field allows API clients to pass runtime parameters to the agent at request time. These parameters flow into the agent factory's dependency resolution — specifically, they fill agent constructor parameters that are not already set by the agent's static configuration.

How it works:

1. The client sends bot_params: {"search_scope": "internal"} in the request.
2. The handler sanitizes the dict (protected keys like tenant, request_headers, index_id are always stripped).
3. The agent factory resolves each constructor parameter by checking the agent's static agent_configuration first, then falling back to handler_params (which includes the sanitized bot_params).
4. If the agent class declares a parameter matching a key in bot_params, and the static configuration does not already set it, the runtime value is used.

Security model:

• Static agent_configuration always takes precedence — bot_params cannot override values the agent developer has locked in configuration.
• For dict-typed parameters, values are deep-merged with configuration taking precedence.
• Protected system keys (tenant, request_headers, index_id) are always stripped regardless of what the client sends.

When to use:

Use bot_params when the agent developer has designed specific constructor parameters to be overridable at runtime. Common patterns include passing a user-selected scope, language preference, or feature flag. The exact parameters available depend on the specific agent's implementation.

Error Handling

HTTP Errors

Errors from the chat service return JSON with a detail field:

{"detail": "Error description"}

Status	Meaning	Common Causes
400	Bad Request	Unknown agent_identifier, agent not streamable for the streaming endpoint, malformed request body, mutually exclusive fields both set
401	Unauthorized	Missing or invalid API key / Bearer token (returned by the API gateway)
403	Forbidden	Valid credentials but insufficient permissions for this tenant
404	Not Found	message_id not found or expired when reconnecting or cancelling a stream
422	Validation Error	Request body fails schema validation
500	Internal Server Error	Unexpected server-side failure

note

401 responses come from the API gateway and use {"message": "Unauthorized"} rather than {"detail": "..."}.

Validation Errors (422)

Validation errors include per-field details in the standard FastAPI/Pydantic format:

{
  "detail": [
    {
      "loc": ["body", "conversation", 0, "sender"],
      "msg": "value is not a valid enumeration member",
      "type": "value_error.enum"
    }
  ]
}

Streaming Errors

If the agent encounters an error during an active SSE stream, an error event is sent with a plain-text data field (not JSON):

event: error
data: Internal streaming error

When you receive an error event, close the connection. If the error occurred mid-stream, you can attempt reconnection using the last received message_id and event_index.

Deprecated Fields

Field	Replacement
function_call_request / function_call_response	content_parts with type: "tool" — see Content Parts
function_specs	Tool specifications are now configured server-side
image_uri	Media should be handled via content parts