Create a research request

Runs a deep research task and streams the result back as Server-Sent Events.

POSThttps://api.bahith.dev/v1/research

Request

Authenticate with the X-API-Key header (see Authentication) and send a JSON body.

Body parameters

querystringrequired

The research question or topic. 1–10,000 characters.

reasoning_level"low" | "medium" | "high"default: "medium"

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.

optionsobjectoptional

Optional flags controlling stream verbosity (see below).

request_idstringoptional

A client-provided ID echoed back on every event for correlation. If omitted, Bahith generates one (req_…).

metadataobjectoptional

Arbitrary key/value pairs passed through for your own bookkeeping.

options

include_thinkingbooleandefault: true

Emit research.thinking.delta events containing the model's intermediate reasoning. Set false to suppress them.

include_tool_callsbooleandefault: true

Emit research.tool_call.started / research.tool_call.completed events and include tool-call records. Set false to suppress them.

Example request

bash
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 }
  }'
code

## 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:

json
{
  "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

answerstringoptional

The synthesized answer, with inline <cite id="…">…</cite> tags.

answer_cleanstringoptional

The same answer with citation tags stripped. Citation start_offset/end_offset index into this string.

citationsCitation[]optional

One entry per cited claim. See Citations for the full anatomy of a citation, including the source-sentence anchor.

sources_summarySourceSummary[]optional

Sources deduplicated by URL, each with the citation IDs referencing it, sorted by citation count.

usageUsageInfooptional

Iteration count, tool calls, sources cited, token estimates, and latency.

Try it