Skip to main content

Research

Ask a natural-language question and get a cited answer assembled from your collection.

Get a one-shot cited answer#

Buffered research call that returns the final answer with its sources.

Best for backend jobs and environments that cannot consume Server-Sent Events. The HTTP request stays open for the duration of the research run and returns one JSON response. For interactive UIs, prefer streaming.

const result = await client.research.researchSync(
  'COLLECTION_ID',
  'What did the company say about indemnification?',
  { depth: 'balanced' },
)

console.log(result.answer)
for (const source of result.sources) {
  console.log('—', source.filename, '§', source.sectionTitle)
}

Response

{
  "sessionId": "rsn_abc",
  "answer": "The contracts handle indemnification...",
  "sources": [
    {
      "chunkId": "chk_8a",
      "sectionId": "sec_b4f9",
      "sectionTitle": "Indemnification",
      "sectionLevel": 2,
      "documentId": "doc_a1",
      "filename": "msa.pdf",
      "content": "Each party shall indemnify..."
    }
  ]
}

See also

Stream a research answer#

Consume the SSE event stream and render the answer as it generates.

Streaming yields four event types: `tool_call` (a retrieval tool was invoked), `chunk` (a token of the answer), `done` (the final session ID and the source list), and `error`. Render tokens as they arrive for a responsive UI; collect sources from the `done` event for citations.

dewey research my-docs "summarize the findings" --depth deep

# 🔍 hybrid_search("revenue trends q3 2026")
# 🔍 hybrid_search("operating expenses 2026")
# Revenue grew 18% year-over-year, driven primarily by...
#
# Sources:
#   [1] report.pdf — Executive summary
#   [2] report.pdf — Risk factors

See also

Pick depth and model#

Tune compute spend by depth level and choose the model that runs the loop.

Depth controls how many retrieval tool calls the agent is allowed to make: `quick` (≤2), `balanced` (≤5, the default), `deep` (≤10), `exhaustive` (≤20). `model` picks the LLM driving the loop; defaults to a fast model. Heavier depth + heavier model = better citations and synthesis, more cost.

# Heaviest synthesis, GPT-5 driving the loop
dewey research my-docs "compare q2 vs q3 revenue drivers" \
  --depth exhaustive --model gpt-5

See also

Scope research to a tag subset#

Run research over only the documents you care about.

Same tag and metadata filters as retrieval — pass `tags` (must have all), `anyTags` (must have any), or `metadata` to constrain which documents the research agent's tools can return. Useful when one collection holds multiple domains.

const result = await client.research.researchSync(
  'COLLECTION_ID',
  'what risks do contracts flag?',
  { depth: 'balanced', tags: ['contracts', 'legal'] },
)

See also

Use your own provider key#

Run research on your own OpenAI, Anthropic, or Gemini key.

Bring your own key (BYOK). Once a provider key is registered for your project, research and agent calls that target that provider's models bill against your account instead of Dewey's shared pool. Register the key first (see Provider keys), then pass any supported model from that provider.

// 1. Register your Anthropic key once (see provider-keys/add).
// 2. Any research call against a Claude model uses it.
const result = await client.research.researchSync(
  'COLLECTION_ID',
  'compare q2 vs q3 revenue drivers',
  { depth: 'deep', model: 'claude-opus-4-7' },
)

See also

List and replay past sessions#

Browse history and re-fetch a prior session's answer and sources.

Every research call persists as a session you can re-fetch by ID. Sessions are listed via `GET /v1/collections/:id/research`; an individual session's answer and sources are at `GET /v1/research/:sessionId`. The SDKs don't currently wrap these — call them with `fetch`/`requests` against your API key.

# Coming soon — for now, hit the REST endpoints directly.