Chat API

Drive conversations programmatically — synchronous or streaming, with retrieval sources in every reply.

How a turn is processed

Every message — from the widget, the API, or an IM channel — runs the same pipeline. Auth and the membership/quota gates come first, then retrieval grounds the answer, then the tool loop runs, and the turn is persisted field-encrypted while memory and cross-channel delivery happen in the background.

Synchronous chat

curl https://chat.agent4.io/chat \
  -H "X-API-Key: tk_live_…" \
  -H "X-End-User: lead-1024" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I need a bridge loan for 3 months",
    "session_id": null,
    "agent": null
  }'

Request fields

Field	Type	Notes
`message`	string	The user's message.
`session_id`	string \| null	Omit to start a new session; pass the returned id to continue it.
`agent`	string \| null	Agent name; omit for the tenant default.
`k`	number \| null	Override how many knowledge chunks to retrieve.
`images`	string[] \| null	Data-URL (base64) images for this turn (multimodal).
`audio`	string \| null	Data-URL audio; transcribed server-side and used as the message.

Response

{
  "session_id": "6f1e…",
  "reply": "For a 3-month bridge loan our current terms are…",
  "sources": [
    { "document_id": "a3b4…", "distance": 0.18 }
  ],
  "transcript": null
}

sources lists the knowledge-base documents the answer was grounded in — use them to render citations. transcript is set when you sent audio.

Streaming

POST /chat/stream takes the same body and returns server-sent events, so you can render tokens as they arrive:

curl -N https://chat.agent4.io/chat/stream \
  -H "X-API-Key: tk_live_…" \
  -H "X-End-User: lead-1024" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Compare your 3 and 6 month terms" }'

Language

The reply language follows the conversation. Send an Accept-Language header to steer system messages and follow-up emails; the five platform languages are en, zh, zh-TW, es, ru.

The full endpoint catalog — sessions, documents, spaces, usage — is rendered from the live OpenAPI schema in the console's API docs page.

Authentication

Spaces & knowledge