Skip to main content

​
Overview

Mave is Mavera’s AI-powered research agent that conducts comprehensive investigations using multiple data sources, personas, and built-in fact-checking. Unlike simple chat, Mave uses a 5-phase orchestration process to deliver well-researched responses with sources.

​
How It Works

1

Triage

Mave analyzes your query complexity and determines if clarification is needed. Queries are classified as Simple, Moderate, Complex, or Strategic.
2

Planning

Mave creates an execution strategy: which personas to use, what data sources to query, and how to structure the research.
3

Research

Mave executes tool calls in parallel — web search, news search, SEO data, and more — to gather comprehensive information.
4

Execution

Mave generates a response incorporating persona perspectives and citing research data.
5

Validation

Mave performs a reality check to assess accuracy, flag unsupported claims, and provide 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"},
    json={
        "message": "Analyze the competitive landscape for electric vehicles in Europe"
    }
)

result = response.json()
print(f"Thread ID: {result['thread_id']}")
print(f"Response: {result['content']}")
print(f"Sources: {result['sources']}")
print(f"Credits used: {result['usage']['credits_used']}")

​
Continuing Conversations

Use the thread_id to continue conversations with context: 
# First message - creates a new thread
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"]

# Follow-up message - uses same thread
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
    }
)

​
Streaming

Enable streaming for real-time responses: 
import httpx

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?", "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="")

​
Response Format

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

​
Thread Management

​
List Threads

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"

​
Data Sources

Mave can access multiple data sources during research:
SourceDescription
Web SearchReal-time web information via Tavily
News SearchRecent news articles via Perigon
SEO DataDomain metrics and competitive intelligence via SEMrush
Knowledge BaseYour custom business knowledge (if configured)

​
Credit Usage

Mave queries are more expensive than simple chat because they involve multiple phases and data sources:
Query TypeTypical Cost
Simple question10-15 credits
Moderate research20-30 credits
Complex analysis30-50 credits
Strategic deep-dive40-75 credits

​
Best Practices

Clear, specific questions lead to better research. “Analyze Tesla’s market position in Germany in 2024” is better than “Tell me about Tesla.”
Continue conversations in the same thread to maintain context and reduce redundant research.
Review validation.confidence_score and validation.hallucination_risk for important decisions.
Mave queries use more credits. Use simple chat for basic questions.

API Reference

See the full API specification