Skip to main content
The Research module runs a multi-stage pipeline that decomposes a topic into subtopics, queries various sources (RAG, paper search, web search), and produces a full research report.

​
Endpoints

​
POST /api/v1/research/optimize_topic

Rephrase or iteratively refine a research topic. On the first call (iteration: 0) it reformulates the raw topic. On subsequent calls it incorporates feedback.

​
Request body

​
topic
string
required
The research topic or, on iteration > 0, user feedback on the previous result.
​
iteration
number
default:"0"
Iteration index. 0 for the first call; increment for each feedback round.
​
previous_result
object
The result object returned by the previous call. Required when iteration > 0.
​
kb_name
string
default:"ai_textbook"
Knowledge base to use for context.

​
Response

​
optimized_topic
string
The reformulated topic string.
​
error
string
Present only if an error occurred.
curl -X POST http://localhost:8001/api/v1/research/optimize_topic \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "how does attention work in transformers",
    "iteration": 0,
    "kb_name": "ai_textbook"
  }'

{
  "optimized_topic": "Attention mechanisms in transformer architectures: mathematical foundations and practical applications"
}

​
WS /api/v1/research/run

Run the full deep research pipeline. The server streams log lines, progress events, and the final report over the connection.

​
Initial message

Send this JSON object immediately after the connection opens.
​
topic
string
required
The research topic.
​
kb_name
string
default:"ai_textbook"
Knowledge base to use for RAG queries.
​
plan_mode
string
default:"medium"
Research depth. One of quick, medium, deep, or auto.
ModeSubtopicsMax iterations per topicMode
quick22Fixed
medium54Fixed
deep87Fixed
autoUp to 86Flexible
​
enabled_tools
string[]
default:"[\"RAG\"]"
Tools to enable during research. Any combination of "RAG", "Paper", and "Web". Code execution is always enabled.
​
skip_rephrase
boolean
default:"false"
Skip the internal topic rephrasing step.

​
Streaming messages

​
type
string
required
Message type. One of: task_id, status, log, progress, result, error.
​
task_id
string
Returned in the task_id message. Unique identifier for this run.
​
content
string
Returned in status, log, and error messages.
​
research_id
string
Returned in status (started) and result messages. Identifies this research run.
​
report
string
Returned in the result message. Full Markdown content of the research report.
​
metadata
object
Returned in the result message. Pipeline metadata including sources and statistics.

​
Example

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

ws.onopen = () => {
  ws.send(JSON.stringify({
    topic: "Attention mechanisms in transformer architectures",
    kb_name: "ai_textbook",
    plan_mode: "medium",
    enabled_tools: ["RAG", "Web"]
  }));
};

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

  if (msg.type === 'result') {
    console.log('Report:', msg.report);
  } else if (msg.type === 'log') {
    console.log('[log]', msg.content);
  }
};
Example streaming messages: 
{ "type": "task_id", "task_id": "research_20250101_xyz" }
{ "type": "status", "content": "started", "research_id": "research_20250101_xyz" }
{ "type": "log", "content": "Decomposing topic into 5 subtopics..." }
{ "type": "progress", "stage": "researching", "subtopic": "Self-attention", "percent": 40 }
{ "type": "result",
  "report": "# Attention mechanisms in transformer architectures\n\n...",
  "metadata": { "sources": 12, "duration_seconds": 47 },
  "research_id": "research_20250101_xyz" }
The log messages are captured stdout from the pipeline and may include rich formatting that has been stripped. Use them for debugging or live status display.

Build docs developers (and LLMs) love

Get started for freeTalk to us