Quickstart: Mave Agent

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:

Triage

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

Planning

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

Research

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

Execution

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

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.

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"])

const API_KEY = "mvra_live_your_key_here";
const URL = "https://app.mavera.io/api/v1/mave/chat";

const response = await fetch(URL, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "What are the main factors driving electric vehicle adoption in Europe in 2024?",
  }),
});

const result = await response.json();

if (result.error) {
  throw new Error(result.error.message);
}

console.log("Thread ID:", result.thread_id);
console.log("Response preview:", result.content.slice(0, 300) + (result.content.length > 300 ? "..." : ""));
console.log("Sources count:", result.sources.length);
console.log("Credits used:", result.usage.credits_used);

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": "What are the main factors driving electric vehicle adoption in Europe in 2024?"
  }'

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.

# 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"])

const threadId = result.thread_id;

const followUp = await fetch(URL, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "What about Tesla's market share in Germany specifically?",
    thread_id: threadId,
  }),
});

const followUpResult = await followUp.json();
if (followUpResult.error) throw new Error(followUpResult.error.message);

console.log(followUpResult.content);
console.log("Credits this turn:", followUpResult.usage.credits_used);

# Replace mave_thread_abc123 with your thread_id
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": "What about Tesla'\''s market share in Germany specifically?",
    "thread_id": "mave_thread_abc123"
  }'

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.

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()

const streamResponse = await fetch(URL, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Summarize the latest trends in renewable energy in Europe.",
    stream: true,
  }),
});

const reader = streamResponse.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split("\n");
  buffer = lines.pop() || "";
  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const payload = line.slice(6).trim();
      if (payload === "[DONE]") break;
      try {
        const data = JSON.parse(payload);
        if (data.type === "content" && data.content) {
          process.stdout.write(data.content);
        }
      } catch (_) {}
    }
  }
}
console.log();

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.

# 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,
)

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

# Get thread
curl -s "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"

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.

Getting Started

Core Concepts

Features

SDKs & Libraries

Quickstart: Mave Agent

What You’ll Learn

Prerequisites

How Mave Works (5 Phases)

Step 1: Send Your First Message

Step 2: Understand the Response Shape

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

Step 4: Optional — Enable Streaming

Step 5: List and Manage Threads

Credit Expectations

Common Issues

Next Steps

Mave Agent

Responses API

Credits

API Reference

​What You’ll Learn

​Prerequisites

​How Mave Works (5 Phases)

​Step 1: Send Your First Message

​Step 2: Understand the Response Shape

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

​Step 4: Optional — Enable Streaming

​Step 5: List and Manage Threads

​Credit Expectations

​Common Issues

​Next Steps

Mave Agent

Responses API

Credits

API Reference

What You’ll Learn

Prerequisites

How Mave Works (5 Phases)

Step 1: Send Your First Message

Step 2: Understand the Response Shape

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

Step 4: Optional — Enable Streaming

Step 5: List and Manage Threads

Credit Expectations

Common Issues

Next Steps