Quickstart: Mave Agent

Run your first Mave research query with sources, threads, and follow-up questions in under 10 minutes

What You’ll Learn

In this quickstart you will:

• Understand how Mave differs from simple chat: a 5-phase research process with multiple data sources and fact-checking.
• Send your first message to Mave and receive a researched response with sources and a thread ID.
• Continue the conversation in the same thread for follow-up questions without repeating context.
• Inspect validation (confidence, hallucination risk) and credit usage.
• Optionally list and manage threads via the API.

Mave is best for questions that benefit from live data (web, news, SEO) and cited answers—e.g. market analysis, competitive landscape, or trend research.

Time: About 10 minutes (first response can take 30–90 seconds). Credits: A typical Mave query uses 10–50 credits depending on complexity.

---

Prerequisites

Mavera account with an active subscription and sufficient credits. Check usage at app.mavera.io/settings/usage.

API key from Developer Settings. Keys start with mvra_live_.

HTTP client: Python requests/httpx, Node fetch, or cURL.

Mave is a REST endpoint (POST /mave/chat), not the OpenAI SDK. You’ll use your language’s HTTP client; the Responses API quickstart is optional background.

---

How Mave Works (5 Phases)

Mave doesn’t just reply—it researches your question before answering:

1. Triage

   Classifies your query (Simple, Moderate, Complex, or Strategic) and decides whether to ask for clarification.

2. Planning

   Chooses which personas and data sources to use (web search, news, SEO, knowledge base) and plans the research steps.

3. Research

   Runs tool calls in parallel to gather information from those sources.

4. Execution

   Writes a response that weaves together research and persona perspectives and cites sources.

5. Validation

   Performs a reality check, flags unsupported claims, and returns a confidence score and hallucination risk.

You send a single message (and optionally a thread_id for follow-ups); Mave handles the rest and returns content, sources, validation, and usage.credits_used.

---

Step 1: Send Your First Message

Send a clear, specific question. Broad or vague questions still work but tend to produce broader answers and use more credits.

Python

import requests

API_KEY = "mvra_live_your_key_here"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
URL = "https://app.mavera.io/api/v1/mave/chat"

response = requests.post(
    URL,
    headers=HEADERS,
    json={
        "message": "What are the main factors driving electric vehicle adoption in Europe in 2024?"
    },
)

result = response.json()

# Always check for API errors
if "error" in result:
    raise Exception(result["error"]["message"])

print("Thread ID:", result["thread_id"])
print("Response preview:", result["content"][:300] + "..." if len(result["content"]) > 300 else result["content"])
print("Sources count:", len(result["sources"]))
print("Credits used:", result["usage"]["credits_used"])

Save the returned thread_id (e.g. mave_thread_abc123). You’ll use it for follow-up questions so Mave keeps context.

The first response can take 30–90 seconds while Mave runs research. Use streaming (see below) or a loading state in production so users know the request is in progress.

---

Step 2: Understand the Response Shape

A successful Mave response looks like this (conceptually):

Field	Description
thread_id	Use this in the next request to continue the conversation.
message_id	Unique ID for this assistant message.
content	Full markdown response with analysis and citations.
sources	Array of objects with title, url, snippet (and possibly more).
personas_used	Personas Mave used for the answer (id + name).
validation	passed, confidence_score, hallucination_risk for quality checks.
usage.credits_used	Credits consumed by this request.

Example (simplified):

{
  "thread_id": "mave_thread_abc123",
  "message_id": "msg_xyz789",
  "content": "## Electric Vehicle Adoption in Europe (2024)\n\nSeveral factors are driving adoption...",
  "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 }
}

Use sources to link users to evidence; use validation to decide how much to trust the answer (e.g. show a warning when hallucination_risk is not low).

---

Step 3: Ask a Follow-Up in the Same Thread

Send a second request with the same thread_id so Mave has full context and doesn’t re-research from scratch.

Python

# Assume you have thread_id from the first response
thread_id = result["thread_id"]

follow_up = requests.post(
    URL,
    headers=HEADERS,
    json={
        "message": "What about Tesla's market share in Germany specifically?",
        "thread_id": thread_id,
    },
)

follow_up_result = follow_up.json()
if "error" in follow_up_result:
    raise Exception(follow_up_result["error"]["message"])

print(follow_up_result["content"])
print("Credits this turn:", follow_up_result["usage"]["credits_used"])

Follow-ups in the same thread are typically faster and use fewer credits than starting a new thread, because Mave reuses prior research where relevant.

---

Step 4: Optional — Enable Streaming

For long answers, you can stream content as it’s generated so users see progress immediately.

Python

import httpx
import json

with httpx.stream(
    "POST",
    URL,
    headers=HEADERS,
    json={
        "message": "Summarize the latest trends in renewable energy in Europe.",
        "stream": True,
    },
    timeout=120.0,
) as response:
    for line in response.iter_lines():
        if line.startswith("data: "):
            payload = line[6:].strip()
            if payload == "[DONE]":
                break
            try:
                data = json.loads(payload)
                if data.get("type") == "content" and data.get("content"):
                    print(data["content"], end="", flush=True)
            except json.JSONDecodeError:
                pass
print()

Streaming responses may still include a final non-streamed payload with thread_id, sources, and usage; check the API reference or the actual response format for your version.

---

Step 5: List and Manage Threads

You can list your threads, fetch one thread’s details, or delete a thread when you’re done.

Python

# List threads
list_resp = requests.get(
    "https://app.mavera.io/api/v1/mave/threads",
    headers=HEADERS,
)
threads = list_resp.json()
print(threads)  # Structure may include data[], next_cursor, etc.

# Get one thread
thread_resp = requests.get(
    f"https://app.mavera.io/api/v1/mave/threads/{thread_id}",
    headers=HEADERS,
)
thread_detail = thread_resp.json()

# Delete a thread
del_resp = requests.delete(
    f"https://app.mavera.io/api/v1/mave/threads/{thread_id}",
    headers=HEADERS,
)

Deleting a thread is irreversible; the conversation history for that thread is no longer available.

---

Credit Expectations

Mave is more expensive than simple chat because it runs multiple phases and data sources:

Query type	Typical credits
Simple question	10–15
Moderate research	20–30
Complex analysis	30–50
Strategic deep-dive	40–75

Monitor usage.credits_used and set budget alerts or use Credits best practices so you don’t run out mid-session.

---

Common Issues

Request times out after 30+ seconds

Mave research can take 30–90 seconds. Increase your HTTP client timeout (e.g. 120 seconds) or use streaming so the connection stays active while content is generated.

thread_id not found or 404

The thread may have been deleted or the ID might be from another account/workspace. Start a new conversation by omitting thread_id in the next request.

402 credits_exhausted

Your account has no credits left. Refill credits or enable auto-recharge; see Credits.

429 rate_limit_exceeded

Mave has stricter concurrency limits. Space out requests or implement retries with backoff; see Rate Limits and Errors.

---

Next Steps

Mave Agent

Data sources, validation, and best practices

Responses API

Simpler, cheaper persona-driven responses when you don’t need research

Credits

Allocation, costs by endpoint, and budget alerts

API Reference

Full Mave chat and thread API specification

Use Mave when you need cited, multi-source research. Use the Responses API when you need fast, persona-based conversation without live data.