Chat API

POST /api/v1/chat

Send a message to an agent and get a synchronous response. The request waits until the agent completes its full ReAct loop and returns the final answer.

Request

POST /api/v1/chat
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "message": "What is the weather in London right now?",
  "agent": "Research Agent",
  "session_id": "user-session-123",
  "images": []
}

Request body fields:

Field	Type	Required	Description
message	string	Yes	The user's message
agent	string	No	Agent name or ID. Omit to use the first configured agent.
session_id	string	No	Session identifier for conversation continuity. Auto-generated if omitted.
images	array	No	Base64 data-URI images for multimodal models (max 5). e.g. "data:image/png;base64,..."

Response

{
  "response": "The current weather in London is 12°C and cloudy...",
  "agent_id": "agent-abc123",
  "agent_name": "Research Agent",
  "session_id": "user-session-123"
}

Response fields:

Field	Type	Description
response	string	The agent's final response text
agent_id	string	ID of the agent that responded
agent_name	string	Display name of the agent
session_id	string	Session ID (use in subsequent requests for continuity)

cURL example

curl -X POST http://localhost:8000/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarise the latest news about AI agents",
    "agent": "Research Agent",
    "session_id": "my-session"
  }'

Python example

import requests

response = requests.post(
    "http://localhost:8000/api/v1/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "message": "What is 15% of $2,340?",
        "session_id": "calc-session"
    }
)
data = response.json()
print(data["response"])

---

POST /api/v1/chat/stream

Send a message to an agent and receive a stream of Server-Sent Events (SSE). This lets you display partial results and reasoning steps in real time.

Request

Same as /chat — same fields, same auth.

SSE Event Stream

The response is a stream of data: events. Each event is a JSON object.

Event types:

Type	Description	Fields
session	First event — session metadata	session_id, agent_id, agent_name
status	Agent status update	message
thinking	Agent's internal reasoning (if available)	message
tool_execution	Agent is calling a tool	tool_name, args
tool_result	Tool call completed	tool_name, preview
llm_thought	Agent's chain-of-thought	thought, turn
response	Final response (last content event)	content, intent, session_id
error	An error occurred	message
done	Stream ended	—

cURL example

curl -X POST http://localhost:8000/api/v1/chat/stream \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{"message": "Research quantum computing trends", "session_id": "stream-test"}'

Example stream output:

data: {"type": "session", "session_id": "stream-test", "agent_id": "agent-abc", "agent_name": "Research Agent"}

data: {"type": "status", "message": "Thinking..."}

data: {"type": "tool_execution", "tool_name": "browser_navigate", "args": {"url": "https://arxiv.org/..."}}

data: {"type": "tool_result", "tool_name": "browser_navigate", "preview": "Quantum computing in 2024..."}

data: {"type": "response", "content": "Here are the key trends in quantum computing...", "session_id": "stream-test"}

data: {"type": "done"}

JavaScript example

const response = await fetch("http://localhost:8000/api/v1/chat/stream", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Write a Python script to parse JSON",
    session_id: "js-session"
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const text = decoder.decode(value);
  const lines = text.split("\n");
  
  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const event = JSON.parse(line.slice(6));
      if (event.type === "response") {
        console.log("Final:", event.content);
      } else if (event.type === "tool_execution") {
        console.log("Using tool:", event.tool_name);
      }
    }
  }
}

---

GET /api/v1/agents

List all configured agents.

curl http://localhost:8000/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  {
    "id": "agent-abc123",
    "name": "Research Agent",
    "type": "conversational",
    "model": "claude-3-5-sonnet-20241022",
    "description": "Deep research using web browsing"
  }
]

---

GET /api/v1/agents/{agent_id}

Get details for a specific agent.

curl http://localhost:8000/api/v1/agents/agent-abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"