Mave Agent

Mave is Mavera’s AI-powered research agent. Unlike the Responses API, which answers questions from a single persona’s perspective, Mave conducts research — searching the web, pulling news articles, querying SEO data, and synthesizing findings into cited, validated reports. Every Mave response includes sources with URLs, a confidence score, and a hallucination risk assessment. It’s designed for questions where you need facts, not just opinions.

Mave uses a 5-phase orchestration process: triage, planning, research, execution, and validation. This is why responses take longer (5–30 seconds) but are significantly more grounded than standard chat.

How It Works

Triage

Mave analyzes your query complexity and determines if clarification is needed. Queries are classified as Simple, Moderate, Complex, or Strategic — each triggering a different depth of research.

Planning

Mave creates an execution strategy: which personas to consult, what data sources to query, what search terms to use, and how to structure the final output.

Research

Mave executes tool calls in parallel — web search, news search, SEO data, and knowledge base queries — to gather comprehensive information from multiple angles.

Execution

Mave synthesizes all research into a coherent response, incorporating persona perspectives and inline citations to source material.

Validation

Mave performs a reality check: assessing accuracy, flagging unsupported claims, evaluating hallucination risk, and producing a confidence score.

Basic Usage

import requests

response = requests.post(
    "https://app.mavera.io/api/v1/mave/chat",
    headers={
        "Authorization": "Bearer mvra_live_your_key_here",
        "Content-Type": "application/json"
    },
    json={
        "message": "Analyze the competitive landscape for electric vehicles in Europe"
    }
)

result = response.json()
print(f"Thread ID: {result['thread_id']}")
print(f"\n{result['content']}")

print("\n--- Sources ---")
for source in result["sources"]:
    print(f"  [{source['title']}]({source['url']})")

print(f"\nConfidence: {result['validation']['confidence_score']}")
print(f"Hallucination risk: {result['validation']['hallucination_risk']}")
print(f"Credits used: {result['usage']['credits_used']}")

const response = await fetch("https://app.mavera.io/api/v1/mave/chat", {
  method: "POST",
  headers: {
    Authorization: "Bearer mvra_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Analyze the competitive landscape for electric vehicles in Europe",
  }),
});

const result = await response.json();
console.log(`Thread ID: ${result.thread_id}`);
console.log(result.content);

console.log("\n--- Sources ---");
result.sources.forEach((source) => {
  console.log(`  [${source.title}](${source.url})`);
});

console.log(`\nConfidence: ${result.validation.confidence_score}`);
console.log(`Hallucination risk: ${result.validation.hallucination_risk}`);

curl -X POST https://app.mavera.io/api/v1/mave/chat \
  -H "Authorization: Bearer mvra_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Analyze the competitive landscape for electric vehicles in Europe"
  }'

Multi-Turn Threads

Every Mave response returns a thread_id. Pass it back in subsequent requests to maintain conversation context. Mave remembers the full research history within a thread, so follow-up questions can reference earlier findings without re-doing the research.

headers = {
    "Authorization": "Bearer mvra_live_your_key_here",
    "Content-Type": "application/json"
}

response1 = requests.post(
    "https://app.mavera.io/api/v1/mave/chat",
    headers=headers,
    json={"message": "Analyze the EV market in Europe"}
)
thread_id = response1.json()["thread_id"]
print(response1.json()["content"])

response2 = requests.post(
    "https://app.mavera.io/api/v1/mave/chat",
    headers=headers,
    json={
        "message": "What about Tesla's market share specifically?",
        "thread_id": thread_id
    }
)
print(response2.json()["content"])

response3 = requests.post(
    "https://app.mavera.io/api/v1/mave/chat",
    headers=headers,
    json={
        "message": "Compare that with BYD's growth trajectory",
        "thread_id": thread_id
    }
)
print(response3.json()["content"])

const headers = {
  Authorization: "Bearer mvra_live_your_key_here",
  "Content-Type": "application/json",
};

const res1 = await fetch("https://app.mavera.io/api/v1/mave/chat", {
  method: "POST",
  headers,
  body: JSON.stringify({ message: "Analyze the EV market in Europe" }),
});
const { thread_id: threadId, content: content1 } = await res1.json();
console.log(content1);

const res2 = await fetch("https://app.mavera.io/api/v1/mave/chat", {
  method: "POST",
  headers,
  body: JSON.stringify({
    message: "What about Tesla's market share specifically?",
    thread_id: threadId,
  }),
});
console.log((await res2.json()).content);

const res3 = await fetch("https://app.mavera.io/api/v1/mave/chat", {
  method: "POST",
  headers,
  body: JSON.stringify({
    message: "Compare that with BYD's growth trajectory",
    thread_id: threadId,
  }),
});
console.log((await res3.json()).content);

Follow-up messages in the same thread are cheaper because Mave can reuse earlier research context. Start new threads only when changing topics entirely.

Streaming

Enable streaming for real-time display of Mave’s response as it generates.

import httpx
import json

with httpx.stream(
    "POST",
    "https://app.mavera.io/api/v1/mave/chat",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={"message": "What are the latest AI trends in healthcare?", "stream": True}
) as response:
    for line in response.iter_lines():
        if line.startswith("data: "):
            data = json.loads(line[6:])
            if data.get("type") == "content":
                print(data["content"], end="", flush=True)
            elif data.get("type") == "sources":
                print("\n\n--- Sources ---")
                for source in data["sources"]:
                    print(f"  {source['title']}: {source['url']}")
            elif data.get("type") == "validation":
                print(f"\nConfidence: {data['confidence_score']}")
            elif data.get("type") == "done":
                print(f"\nCredits used: {data['usage']['credits_used']}")

const response = await fetch("https://app.mavera.io/api/v1/mave/chat", {
  method: "POST",
  headers: {
    Authorization: "Bearer mvra_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "What are the latest AI trends in healthcare?",
    stream: true,
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const lines = decoder.decode(value).split("\n");
  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const data = JSON.parse(line.slice(6));
      if (data.type === "content") {
        process.stdout.write(data.content);
      } else if (data.type === "sources") {
        console.log("\n\n--- Sources ---");
        data.sources.forEach((s) => console.log(`  ${s.title}: ${s.url}`));
      } else if (data.type === "validation") {
        console.log(`\nConfidence: ${data.confidence_score}`);
      }
    }
  }
}

SSE event types:

Event Type	Content
`content`	Text chunk of the response
`sources`	Array of source objects with title, URL, and snippet
`validation`	Confidence score and hallucination risk
`done`	Final event with usage data

Sources and Citations

Every Mave response includes a sources array with the materials it used during research.

{
  "sources": [
    {
      "title": "European EV Sales Report 2024",
      "url": "https://example.com/report",
      "snippet": "EV adoption in Europe grew 25% year-over-year, with Norway leading at 82% market share...",
      "source_type": "web"
    },
    {
      "title": "Tesla Q4 2024 Earnings Call",
      "url": "https://example.com/earnings",
      "snippet": "European deliveries increased 18% compared to Q3...",
      "source_type": "news"
    }
  ]
}

Source types include web (general web search), news (news articles), seo (SEO/domain data), and knowledge_base (your custom knowledge).

Always verify critical citations by visiting the source URLs. While Mave’s validation phase reduces hallucination, no AI system produces perfectly accurate output 100% of the time.

CircleMind Knowledge Base

CircleMind is Mavera’s knowledge base layer. When configured, Mave automatically searches your custom knowledge alongside public web data, grounding responses in your proprietary information.

How It Works

Upload documents to your CircleMind knowledge base (PDFs, docs, text files)
Mave automatically queries your knowledge base during the Research phase
Results are blended with web and news data, with source attribution

Querying with Knowledge Base

response = requests.post(
    "https://app.mavera.io/api/v1/mave/chat",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={
        "message": "What does our internal research say about customer churn in Q3?",
        "use_knowledge_base": True
    }
)

for source in response.json()["sources"]:
    if source["source_type"] == "knowledge_base":
        print(f"Internal source: {source['title']}")

CircleMind knowledge base queries are included in Mave’s credit cost — no additional charge per knowledge base lookup. See CircleMind docs for setup instructions.

Data Sources

Mave can access multiple data sources during the Research phase:

Source	Provider	Data	When Used
Web Search	Tavily	Real-time web pages, articles, documentation	Most queries
News Search	Perigon	Recent news articles, press releases	Current events, market updates
SEO Data	SEMrush	Domain metrics, traffic, keyword rankings	Competitive analysis
Knowledge Base	CircleMind	Your uploaded documents	When `use_knowledge_base: true`

Thread Management

List Threads

response = requests.get(
    "https://app.mavera.io/api/v1/mave/threads",
    headers={"Authorization": "Bearer mvra_live_your_key_here"}
)

for thread in response.json()["data"]:
    print(f"{thread['id']} — {thread['title']} — {thread['message_count']} messages")

curl https://app.mavera.io/api/v1/mave/threads \
  -H "Authorization: Bearer mvra_live_your_key_here"

Get Thread Details

curl https://app.mavera.io/api/v1/mave/threads/mave_thread_abc123 \
  -H "Authorization: Bearer mvra_live_your_key_here"

Delete Thread

curl -X DELETE https://app.mavera.io/api/v1/mave/threads/mave_thread_abc123 \
  -H "Authorization: Bearer mvra_live_your_key_here"

Response Format

{
  "thread_id": "mave_thread_abc123",
  "message_id": "msg_xyz789",
  "content": "## Electric Vehicle Market Analysis\n\nBased on my research across multiple sources...",
  "sources": [
    {
      "title": "European EV Sales Report 2024",
      "url": "https://example.com/report",
      "snippet": "EV adoption in Europe grew 25% year-over-year...",
      "source_type": "web"
    }
  ],
  "personas_used": [
    {
      "id": "persona_123",
      "name": "Industry Analyst"
    }
  ],
  "validation": {
    "passed": true,
    "confidence_score": 0.89,
    "hallucination_risk": "low",
    "unsupported_claims": []
  },
  "usage": {
    "credits_used": 35
  }
}

Validation Object

The validation field provides transparency into Mave’s self-assessment:

Field	Type	Description
`passed`	boolean	Whether the response passed the reality check
`confidence_score`	number (0–1)	Overall confidence in the accuracy of the response
`hallucination_risk`	string	`"low"`, `"medium"`, or `"high"`
`unsupported_claims`	array	Statements that couldn’t be verified by sources

When to Use Mave vs Chat

Need	Use Chat	Use Mave
Persona perspective on a topic	Yes	—
Real-time web data with citations	—	Yes
Quick conversational interaction	Yes	—
Multi-source research report	—	Yes
Structured JSON output	Yes	—
Fact-checked analysis	—	Yes
Tool calling / function calling	Yes	—
Knowledge base integration	—	Yes
Cost per query	1–5 credits	10–75 credits
Response time	< 3 seconds	5–30 seconds

Combine both: Use Mave to research a topic, then use Chat with a specific persona to explore how that audience would react to the findings. This gives you both factual grounding and audience perspective.

Credit Usage

Mave queries are more expensive than Chat because they involve multiple research phases and data source calls.

Query Complexity	Typical Cost	Example
Simple	10–15 credits	”What is the population of France?”
Moderate	20–30 credits	”Summarize recent AI regulation in the EU”
Complex	30–50 credits	”Compare market strategies of top 5 EV brands in Europe”
Strategic	40–75 credits	”Full competitive landscape analysis for fintech in Southeast Asia”

Follow-up messages in the same thread typically cost 30–50% less than the initial query.

Best Practices

Be specific in your queries

Clear, specific questions lead to better research. “Analyze Tesla’s market position in Germany in 2024” produces a more focused, useful report than “Tell me about Tesla.”

Use threads for follow-ups

Continue conversations in the same thread to maintain context and reduce redundant research. Mave can reference earlier findings in follow-up responses.

Check the validation results

Review validation.confidence_score and validation.hallucination_risk before relying on the output for important decisions. Scores below 0.7 warrant additional verification.

Enable streaming for long queries

Complex and strategic queries can take 15–30 seconds. Streaming lets you display progress to users in real time instead of showing a loading spinner.

Use knowledge base for proprietary data

When your question involves internal data, enable CircleMind to blend your proprietary knowledge with public web research.

Use Chat for persona opinions, Mave for facts

Don’t use Mave when you just need a persona’s perspective — that’s what Chat is for. Use Mave when you need researched, cited, fact-checked information.

Next Steps

Quickstart: Mave

First Mave query in 5 minutes

Mave Research Report

Build a full report from a Mave session

CircleMind

Set up your knowledge base

API Reference

Full API specification

Getting Started

Core Concepts

Features

SDKs & Libraries

How It Works

Basic Usage

Multi-Turn Threads

Streaming

Sources and Citations

CircleMind Knowledge Base

How It Works

Querying with Knowledge Base

Data Sources

Thread Management

List Threads

Get Thread Details

Delete Thread

Response Format

Validation Object

When to Use Mave vs Chat

Credit Usage

Best Practices

Next Steps

Quickstart: Mave

Mave Research Report

CircleMind

API Reference

​How It Works

​Basic Usage

​Multi-Turn Threads

​Streaming

​Sources and Citations

​CircleMind Knowledge Base

​How It Works

​Querying with Knowledge Base

​Data Sources

​Thread Management

​List Threads

​Get Thread Details

​Delete Thread

​Response Format

​Validation Object

​When to Use Mave vs Chat

​Credit Usage

​Best Practices

​Next Steps

Quickstart: Mave

Mave Research Report

CircleMind

API Reference

How It Works

Basic Usage

Multi-Turn Threads

Streaming

Sources and Citations

CircleMind Knowledge Base

How It Works

Querying with Knowledge Base

Data Sources

Thread Management

List Threads

Get Thread Details

Delete Thread

Response Format

Validation Object

When to Use Mave vs Chat

Credit Usage

Best Practices

Next Steps