Talking to Mave

Mave is how a non-engineer drives the whole platform with a sentence. Under the hood it calls the same tools documented elsewhere — but it decides which ones, in what order.

Two ways to use Mave

Path	Use when
`deep_research` (single tool)	You want a grounded, cited answer to a question — live web search + a Python sandbox. One request, one result.
A run (`POST /api/v1/runs`, streaming)	You want Mave to do work — a goal that spans planning, fielding, and synthesis, with checkpoints and steering.

Path 1 — deep_research (ask Mave a question)

The fastest way to "talk to" Mave. It runs an agent loop with real tools and returns a cited answer.

POST /api/v1/tools/deep_research

{ "question": "What are the fastest-growing SMB fintech segments in 2026, with sources?",
  "context": "We're pricing a $29/mo bookkeeping copilot for solo founders.",
  "web": true,    // allow live web search + fetch (default true)
  "code": true }  // allow the sandboxed Python interpreter (default true)

Response

{ "ok": true, "data": {
  "answer": "Three segments stand out... [1][2]",
  "sources": ["weforum.org", "cbinsights.com"],
  "toolTrace": [ { "kind":"web_search", "detail":"smb fintech growth 2026" },
                 { "kind":"code_execution", "detail":"CAGR calc" } ],
  "ranTools": true, "asOf": "2026-06-30",
  "honesty": { "basis": "live-evidence" } } }

deep_research answers from real evidence (basis: "live-evidence"), cited or computed in the sandbox. It never fabricates synthetic-audience opinion — for what people think, run a conversation; for what's true in the market, ask Mave.

There's also ask_research — a lighter Q&A when you don't need the full tool loop.

Path 2 — a run (hand Mave a goal)

Start a run with a one-sentence goal. Mave plans first, then executes, streaming Server-Sent Events as it goes.

POST /api/v1/runs

{ "goal": "Find the strongest objection to a $29/mo bookkeeping app among solo founders, and what would overcome it." }
# → text/event-stream of MaveEvents (see below)

The event stream

Each SSE data: line is a typed MaveEvent. The ones you'll act on:

Event	Meaning
`thinking.delta`	Mave's reasoning, streamed (plan- or step-scoped).
`step.started` / `step.completed`	A pipeline step began / finished (with `creditsUsed`).
`step.tool_input`	The exact input Mave is sending to a tool (full transparency).
`checkpoint.reached`	Mave paused for your approval (e.g. before an expensive fielding step). Carries `estCredits` + a summary.
`clarification.requested`	Mave needs a decision from you (carries a `question` + optional `options`).
`insight.produced`	The final cited Insight is ready (`insightId` + `confidence`).
`step.failed`	A step failed (with whether it's `recoverable` + the `nextAction`).

Responding to checkpoints & clarifications

When the stream emits a checkpoint.reached or clarification.requested, resolve it with:

POST /api/v1/runs/{runId}/control

{ "command": "approve" }                      // let an expensive step proceed
{ "command": "reject" }                        // skip / cancel that step
{ "command": "answer", "answer": "Focus on teams of 5-20, not solo founders." }   // answer a clarification

This is the human-in-the-loop seam: Mave proposes, you dispose. It won't burn a big fielding budget without a green light at the checkpoint.

Steering a run mid-flight

You can redirect a run without restarting it. Steering re-plans the not-yet-run tail:

POST /api/v1/runs/{runId}/control

{ "command": "steer", "answer": "Actually, compare against QuickBooks specifically." }
# also: { "command": "pause" } | { "command": "resume" } | { "command": "stop" }  (stop refunds unused credits)

Inspecting a run

The public serverless deployment does not currently expose a durable detached Mave runner. mave_run rejects rather than returning a disposable run ID. For API automation, call the bounded granular tools directly and persist their returned audience, study, and insight IDs in your client.

Run bounded research directly

POST /api/v1/tools/build_audience_from_description
{ "description": "US egg buyers considering a step up from commodity eggs", "targetSize": 600 }

POST /api/v1/tools/run_study
{ "audienceId": "aud_...", "n": 100, "questions": [{ "id": "q1", "text": "...", "responseType": "open_text" }] }

mave_get_plan and mave_get_run remain useful for durable run IDs created by supported Mave surfaces. A durable background worker must be connected before detached mave_run orchestration is enabled.

fast vs deep

Runs take a depth: fast (a tight pipeline, fewer steps, cheaper) or deep (more thorough planning, more fielding, higher confidence). Start fast to scope a question, go deep when the stakes justify the spend.

How Mave relates to everything else

Mave doesn't replace the tools — it conducts them. A "find the strongest objection" goal might have Mave: build/choose an audience → run a focus group → mine the transcript for divergences → branch the sharpest one → synthesize a cited Insight. You could run each of those steps yourself (they're all documented here); Mave just does it autonomously, pausing at the checkpoints you care about.

The bright line holds in Mave too. Mave's research answers are evidence-cited; its audience work computes numbers from real synthetic responses. It never invents respondent data to satisfy a goal — if the evidence isn't there, it tells you.

Recipe: scope, then field

# 1. build or choose an audience
POST /api/v1/tools/build_audience_from_description
{ "description":"Solo founders who stopped using a bookkeeping app during year one", "targetSize":600 }

# 2. run a bounded study with the returned audience id
POST /api/v1/tools/run_study
{ "audienceId":"aud_...", "n":100, "questions":[{ "id":"churn", "text":"What was the main reason you stopped using it?", "responseType":"open_text" }] }

# 3. persist the returned study and insight ids before starting another step

On this page