Chat API

Have conversations with AI using your indexed documents as context.

Send Message

Endpoint

POST /v1/chat

Request Body

{
  "message": "What is our refund policy?",
  "conversationId": "conv_abc123",
  "collections": ["col_xyz789"]
}

Parameters

Parameter	Type	Required	Description
message	string	Yes	User message
conversationId	string	No	Continue existing conversation
collections	string[]	No	Collections to search
model	string	No	LLM model to use
agentId	string	No	Use specific agent

Response

{
  "data": {
    "id": "msg_abc123",
    "conversationId": "conv_xyz789",
    "content": "Our refund policy allows returns within 30 days...",
    "sources": [
      {
        "id": "doc_123",
        "title": "Refund Policy",
        "excerpt": "Returns are accepted within 30 days...",
        "url": "https://..."
      }
    ],
    "usage": {
      "promptTokens": 150,
      "completionTokens": 200,
      "totalTokens": 350
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Streaming Chat

Endpoint

POST /v1/chat/stream

Uses Server-Sent Events (SSE) for streaming responses.

Request

Same as /v1/chat

Response Stream

event: message_start
data: {"id": "msg_abc123", "conversationId": "conv_xyz789"}

event: content_delta
data: {"delta": "Our refund policy "}

event: content_delta
data: {"delta": "allows returns within "}

event: content_delta
data: {"delta": "30 days..."}

event: sources
data: {"sources": [{"id": "doc_123", ...}]}

event: message_end
data: {"usage": {"totalTokens": 350}}

JavaScript Streaming

const stream = await client.chat.stream({
  message: 'What is our refund policy?'
});

for await (const event of stream) {
  if (event.type === 'content_delta') {
    process.stdout.write(event.delta);
  }
}

With Agent

Enable Agent Mode

{
  "message": "Compare Q3 and Q4 sales by region",
  "agentId": "agent_abc123"
}

Agent Events (Streaming)

event: agent_start
data: {"iteration": 1}

event: tool_call
data: {"tool": "search_documents", "params": {"query": "Q3 sales"}}

event: tool_result
data: {"tool": "search_documents", "result": {"count": 5}}

event: agent_thinking
data: {"thought": "Analyzing Q3 data..."}

event: content_delta
data: {"delta": "Based on my analysis..."}

Conversation History

Get Conversation

GET /v1/conversations/{id}

List Conversations

GET /v1/conversations

Delete Conversation

DELETE /v1/conversations/{id}

Example Usage

cURL

curl -X POST https://api.zensearch.ai/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is our refund policy?"
  }'

Python Streaming

async for event in client.chat.stream(
    message="Summarize the Q4 report"
):
    if event.type == "content_delta":
        print(event.delta, end="", flush=True)

Error Responses

Code	Description
400	Invalid request
401	Authentication required
403	Insufficient permissions
429	Rate limit exceeded

Next Steps

• Agents API - Agent management
• Search API - Direct search