Create a research request
Runs a deep research task and streams the result back as Server-Sent Events.
Request
Authenticate with the X-API-Key header (see Authentication)
and send a JSON body.
Body parameters
The research question or topic. 1–10,000 characters.
Sets the maximum number of research iterations. The model may terminate early when it determines it has enough context, performing fewer iterations than this ceiling. Also controls credit costs: low = up to 5 iterations / 10 credits, medium = up to 10 / 15, high = up to 15 / 20.
Optional flags controlling stream verbosity (see below).
A client-provided ID echoed back on every event for correlation. If
omitted, Bahith generates one (req_…).
Arbitrary key/value pairs passed through for your own bookkeeping.
options
Emit research.thinking.delta events containing the
model's intermediate reasoning. Set false to suppress them.
Emit research.tool_call.started /
research.tool_call.completed events and include
tool-call records. Set false to suppress them.
Example request
curl -N -X POST https://api.bahith.dev/v1/research \
-H "Content-Type: application/json" \
-H "X-API-Key: $BAHITH_API_KEY" \
-d '{
"query": "What is RLHF and why does it matter for LLMs?",
"reasoning_level": "medium",
"options": { "include_thinking": true, "include_tool_calls": true }
}'
## Response
The endpoint **always** returns an SSE stream (`Content-Type: text/event-stream`).
There is no non-streaming mode. Each event is a JSON object on a `data:` line:
```json
{
"type": "research.answer.delta",
"request_id": "req_9f2c1a7b8d3e",
"timestamp": "2026-01-15T10:30:45.123Z",
"data": { "content": "Reinforcement", "sequence": 42 }
}
The stream terminates with data: [DONE]. For the full list of event types and
their payloads, see Streaming & events.
The research.completed event
The final data event carries the assembled result:
{
"type": "research.completed",
"request_id": "req_9f2c1a7b8d3e",
"timestamp": "2026-01-15T10:31:12.880Z",
"data": {
"answer": "RLHF is <cite id=\"S_a1b2\">a technique for aligning language models…</cite>",
"answer_clean": "RLHF is a technique for aligning language models…",
"citations": [
{
"id": "S_a1b2",
"cited_text": "a technique for aligning language models",
"start_offset": 8,
"end_offset": 48,
"verified": true,
"supporting_quote": "RLHF fine-tunes a policy against a reward model trained on human preference comparisons.",
"source_anchor": {
"quote": "RLHF fine-tunes a policy against a reward model trained on human preference comparisons.",
"source_start_offset": 512,
"source_end_offset": 599,
"score": 0.91
},
"source": {
"title": "Training language models to follow instructions",
"url": "https://arxiv.org/abs/2203.02155",
"snippet": "…",
"authors": ["Ouyang et al."],
"year": 2022,
"source_type": "paper"
}
}
],
"sources_summary": [
{ "source": { "title": "…", "url": "…" }, "citation_ids": ["S_a1b2"], "citation_count": 1 }
],
"usage": {
"iterations": 10,
"tool_calls": 6,
"sources_cited": 1,
"thinking_tokens": 1840,
"answer_tokens": 420,
"total_tokens": 2260,
"latency_ms": 27650
}
}
}Response fields
The synthesized answer, with inline <cite id="…">…</cite> tags.
The same answer with citation tags stripped. Citation
start_offset/end_offset index into this string.
One entry per cited claim. See Citations for the full anatomy of a citation, including the source-sentence anchor.
Sources deduplicated by URL, each with the citation IDs referencing it, sorted by citation count.
Iteration count, tool calls, sources cited, token estimates, and latency.