Skip to main content
The Solve module runs a multi-agent pipeline that answers questions using knowledge base content. All work is streamed over a WebSocket connection. Sessions persist conversation history across multiple questions.

​
WebSocket endpoint

​
WS /api/v1/solve

Connect to this endpoint to submit a question and stream the solver’s progress and final answer.

​
Initial message

Send this JSON object immediately after the connection opens.
​
question
string
required
The question or problem to solve.
​
kb_name
string
default:"ai_textbook"
Name of the knowledge base to query.
​
session_id
string
An existing session ID to continue a conversation. Omit to start a new session.

​
Streaming messages

The server sends a sequence of typed JSON messages during execution.
​
type
string
required
Message type. One of: session, task_id, status, agent_status, token_stats, progress, log, result, error.
​
session_id
string
Returned in the session message. Use this to continue the conversation in a later connection.
​
task_id
string
Returned in the task_id message. Unique identifier for this run.
​
content
string
Returned in status, log, and error messages. Human-readable text.
​
agent
string
Returned in agent_status messages. Name of the agent that changed state.
​
status
string
Returned in agent_status messages. Current state of the agent, e.g. running, done.
​
all_agents
object
Returned in agent_status messages. Map of all agent names to their current status.
​
stats
object
Returned in token_stats messages.
​
final_answer
string
Returned in the result message. The full Markdown answer from the solver. Image references use /api/outputs/ URLs.
​
output_dir
string
Returned in the result message. Absolute path to the output directory on the server.
​
output_dir_name
string
Returned in the result message. The name component of the output directory (e.g. solve_20250101_120000).
​
metadata
object
Returned in the result message. Additional metadata from the solver run.

​
Example

const ws = new WebSocket('ws://localhost:8001/api/v1/solve');

ws.onopen = () => {
  ws.send(JSON.stringify({
    question: "Explain the backpropagation algorithm.",
    kb_name: "ai_textbook"
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  if (msg.type === 'session') {
    console.log('Session ID:', msg.session_id);
  } else if (msg.type === 'result') {
    console.log('Answer:', msg.final_answer);
  } else if (msg.type === 'error') {
    console.error('Error:', msg.content);
  }
};
Example streaming messages received during a run: 
{ "type": "session", "session_id": "sess_abc123" }
{ "type": "task_id", "task_id": "solve_20250101_120000_xyz" }
{ "type": "status", "content": "started" }
{ "type": "agent_status", "agent": "planner", "status": "running", "all_agents": { "planner": "running" } }
{ "type": "token_stats", "stats": { "model": "gpt-4o", "calls": 3, "cost": 0.012 } }
{ "type": "result",
  "session_id": "sess_abc123",
  "final_answer": "# Backpropagation\n\nBackpropagation is...",
  "output_dir": "/path/to/data/user/solve/solve_xyz",
  "output_dir_name": "solve_xyz",
  "metadata": {} }

​
Session management endpoints

​
GET /api/v1/solve/sessions

List recent solver sessions.

​
Query parameters

​
limit
number
default:"20"
Maximum number of sessions to return.

​
Response

[
  {
    "session_id": "sess_abc123",
    "title": "Explain the backpropagation algorithm...",
    "kb_name": "ai_textbook",
    "created_at": "2025-01-01T12:00:00Z"
  }
]

​
GET /api/v1/solve/sessions/{session_id}

Get a specific session with its full message history.

​
Path parameters

​
session_id
string
required
Session identifier.

​
Response

{
  "session_id": "sess_abc123",
  "title": "Explain the backpropagation algorithm...",
  "kb_name": "ai_textbook",
  "created_at": "2025-01-01T12:00:00Z",
  "messages": [
    { "role": "user", "content": "Explain the backpropagation algorithm." },
    { "role": "assistant", "content": "# Backpropagation\n\n..." }
  ],
  "token_stats": { "model": "gpt-4o", "calls": 3, "cost": 0.012 }
}
Returns 404 if the session is not found.

​
DELETE /api/v1/solve/sessions/{session_id}

Delete a solver session.

​
Path parameters

​
session_id
string
required
Session identifier.

​
Response

{ "status": "deleted", "session_id": "sess_abc123" }
Returns 404 if the session is not found. 
curl -X DELETE http://localhost:8001/api/v1/solve/sessions/sess_abc123

Build docs developers (and LLMs) love

Get started for freeTalk to us